> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant carts

> Merchant cart endpoints for server-managed commerce flows.

## 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):

```bash theme={null}
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:

```json theme={null}
{
  "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": 1766320496,
    "updatedAt": 1766320496
  }
}
```

## 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](/api-spec/commerce/checkout) to start payment and order processing.

Next: [Products](/api-spec/commerce/products)