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:
itemsarray
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: trueanditemOverrides
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 byproductId(+retailerwhen 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
commerceApiKeymerchantApiKey
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.
Was this page helpful?

