Skip to main content

​
Overview

Merchant carts are designed for server-managed commerce flows where the merchant backend controls cart state (customerId, wallet, items) and later creates an invoice/checkout.

​
Authentication

Requires a commerce-scoped API key: x-commerce-api-key: ck_....

​
Request

Endpoints:
  • GET /api/commerce/merchant/carts
  • POST /api/commerce/merchant/carts
  • POST /api/commerce/merchant/carts/items
  • PUT /api/commerce/merchant/carts/items/{itemId}
  • DELETE /api/commerce/merchant/carts/items/{itemId}
  • DELETE /api/commerce/merchant/carts
  • POST /api/commerce/merchant/carts/validate
  • GET /api/commerce/merchant/carts/totals
Example (create a merchant cart): 
BASE_URL=${PEPAY_API_URL}

curl -X POST "$BASE_URL/api/commerce/merchant/carts" \
  -H "x-commerce-api-key: ck_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id":"cust_123",
    "wallet_address":"0x0000000000000000000000000000000000000001",
    "wallet_network":"bsc",
    "item":{
      "productId":"B08N5WRWNW",
      "retailer":"amazon",
      "quantity":1,
      "price":99.99,
      "title":"Echo (4th Gen)"
    }
  }'

​
Response

Representative GET /api/commerce/merchant/carts response: 
{
  "success": true,
  "data": {
    "merchantId": 123,
    "customerId": "cust_123",
    "walletAddress": "0x0000000000000000000000000000000000000001",
    "walletNetwork": "bsc",
    "items": [
      {
        "productId": "B08N5WRWNW",
        "retailer": "amazon",
        "quantity": 1,
        "price": 99.99,
        "title": "Echo (4th Gen)"
      }
    ],
    "subtotal": 99.99,
    "itemCount": 1,
    "createdAt": "2025-12-21T12:34:56.000Z",
    "updatedAt": "2025-12-21T12:34:56.000Z"
  }
}

​
Errors

  • 401 missing/invalid commerce API key
  • 400 validation or business rule violation (invalid wallet, item schema, etc.)

​
Examples

After validating a cart, create a Checkout invoice to start payment and order processing. Next: Products