curl --request POST \
  --url https://api-beta.pepay.io/api/commerce/merchant/checkout/estimate \
  --header 'Content-Type: application/json' \
  --header 'x-commerce-api-key: <api-key>' \
  --data '
{
  "customer_id": "cust_123456",
  "items": [
    {
      "productId": "B08N5WRWNW",
      "quantity": 2,
      "price": 29.99,
      "title": "Test Product"
    }
  ]
}
'

{
  "success": true,
  "data": {
    "estimateId": "550e8400-e29b-41d4-a716-446655440000",
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "customerId": "cust_123456",
    "walletAddress": null,
    "walletNetwork": null,
    "validItems": [
      {
        "productId": "B08N5WRWNW",
        "retailer": "amazon",
        "title": "Item",
        "quantity": 1,
        "price": 9.99,
        "totalPrice": 9.99,
        "metadata": {
          "image": "https://example.com/product.jpg"
        }
      }
    ],
    "invalidItems": [
      {
        "productId": "B000000000",
        "retailer": "amazon",
        "error": "No eligible offers (must be New, Prime/marketplace fulfilled, delivery within 6 days)"
      }
    ],
    "pricing": {
      "subtotal": 9.99,
      "shipping": 1,
      "tax": 0,
      "fees": {
        "fixed": 0,
        "percentage": 0,
        "total": 3
      },
      "total": 13.99
    },
    "feeBreakdown": {
      "shippingBase": 1,
      "commerceFee": 3,
      "totalFees": 4
    },
    "expiresAt": 1765844100,
    "createdAt": 1765843200
  }
}

Commerce

Step 1 - Create checkout estimate (Enhanced)

Creates a checkout estimate with three operational modes:

Mode 1 - Direct Items: Provide items directly (original behavior)

Use when: Guest checkout, quick buy buttons, one-time purchases
Required: items array

Mode 2 - Cart-Based: Pull items from saved cart

Use when: Standard checkout from shopping cart
Required: useCart: true
Cart fetched using customer identification

Mode 3 - Cart with Overrides: Pull from cart with modifications

Use when: Last-minute adjustments, promotions
Required: useCart: true and itemOverrides

Cart behavior (modes 2 & 3):

Pepay does not remove items from the cart automatically.
validItems[] are eligible to be checked out.
invalidItems[] are ineligible right now (e.g., no eligible offers). They stay in the cart unless you remove them.
invalidItems[] intentionally contains the minimal identifiers + reason; match it back to your cart display by productId (+ retailer when relevant).

Customer identification is required: customer_id OR (wallet_address + wallet_network).

POST

api

commerce

merchant

checkout

estimate

curl --request POST \
  --url https://api-beta.pepay.io/api/commerce/merchant/checkout/estimate \
  --header 'Content-Type: application/json' \
  --header 'x-commerce-api-key: <api-key>' \
  --data '
{
  "customer_id": "cust_123456",
  "items": [
    {
      "productId": "B08N5WRWNW",
      "quantity": 2,
      "price": 29.99,
      "title": "Test Product"
    }
  ]
}
'

{
  "success": true,
  "data": {
    "estimateId": "550e8400-e29b-41d4-a716-446655440000",
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "customerId": "cust_123456",
    "walletAddress": null,
    "walletNetwork": null,
    "validItems": [
      {
        "productId": "B08N5WRWNW",
        "retailer": "amazon",
        "title": "Item",
        "quantity": 1,
        "price": 9.99,
        "totalPrice": 9.99,
        "metadata": {
          "image": "https://example.com/product.jpg"
        }
      }
    ],
    "invalidItems": [
      {
        "productId": "B000000000",
        "retailer": "amazon",
        "error": "No eligible offers (must be New, Prime/marketplace fulfilled, delivery within 6 days)"
      }
    ],
    "pricing": {
      "subtotal": 9.99,
      "shipping": 1,
      "tax": 0,
      "fees": {
        "fixed": 0,
        "percentage": 0,
        "total": 3
      },
      "total": 13.99
    },
    "feeBreakdown": {
      "shippingBase": 1,
      "commerceFee": 3,
      "totalFees": 4
    },
    "expiresAt": 1765844100,
    "createdAt": 1765843200
  }
}

Authorizations

x-commerce-api-key

string

header

required

Legacy alias for commerce-scoped API keys. Prefer x-api-key with scope=commerce.

Body

application/json

Option 1
Option 2

Step 1 request. Supports direct items (Mode 1) or cart-based estimation (Modes 2–3). When useCart: true, Pepay reads the saved cart but does not mutate it.

customer_id

string

required

Example:

"cust_123456"

useCart

boolean | null

When true, items are loaded from the saved cart for the provided customer identifier.

items

object[] | null

Mode 1 only (direct items). Forbidden when useCart: true.

Show child attributes

itemOverrides

object[] | null

Mode 3 only. Requires useCart: true. Use quantity: 0 to exclude items for this estimate without mutating the cart.

Show child attributes

addressId

string<uuid> | null

Reserved for future shipping estimates; currently ignored.

shipping_zip

string | null

Reserved for future shipping estimates; currently ignored.

Response

200 - application/json

Estimate created successfully

success

boolean

Example:

true

data

object

Step 1 estimate result (15 minute TTL). Use estimateId for subsequent Step 2 + Step 3 calls.

Show child attributes

Validate cart items Step 2 - Set shipping address