Skip to main content
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": "2025-12-16T00:15:00.000Z",
    "createdAt": "2025-12-16T00:00:00.000Z"
  }
}

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

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.

​
itemOverrides
object[] | null

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

​
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.