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

# Commerce overview

> Commerce API surfaces for search, carts, checkout, orders, and payments.

## Overview

Pepay Commerce APIs power product search, carts, checkout invoicing, order tracking, and commerce payment status.

Key ideas:

* **Base path**: `/api/commerce/*`
* **Merchant addresses**: `/api/v1/commerce/merchant/addresses`
* **SDK mapping**: `pepay.commerce.*`
* **Typical flow**: Search → Merchant carts → Checkout invoice → Orders → Payments

## Authentication

Commerce requests use a commerce-scoped API key:

* `x-commerce-api-key: ck_...`

There are two common patterns:

* **Merchant operations (server-to-server)**: `x-commerce-api-key`
* **Wallet-auth operations (not included here)**: `x-commerce-api-key` + `User-Authorization: Bearer <userAccessToken>`

## Request

Start by checking the Commerce service status:

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/commerce/status" \
  -H "x-commerce-api-key: ck_..."
```

## Response

Representative `GET /api/commerce/status` response:

```json theme={null}
{
  "success": true,
  "data": {
    "status": "available",
    "escrowBalance": 50,
    "minimumRequired": 50,
    "features": {
      "search": true,
      "cart": true,
      "checkout": true,
      "orders": true
    }
  }
}
```

## Errors

* `401` missing/invalid commerce API key
* `429` rate limits (retry with backoff; respect `Retry-After` when present)
* `5xx` transient errors (retry where safe)

## Examples

If you’re building the canonical Commerce experience, follow the sidebar in order:

1. [Commerce APIs](/api-spec/commerce/api-keys) → 2) [Search](/api-spec/commerce/search) → 3) [Checkout](/api-spec/commerce/checkout) → 4) [Orders](/api-spec/commerce/orders)

Next: [Commerce APIs](/api-spec/commerce/api-keys)