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

# Commerce API Overview

> Build custom storefronts using Khaime's Commerce API

# Commerce API

The Commerce API provides a clean, RESTful interface for building custom storefronts. Use these endpoints to list products, handle customer authentication, process checkouts, and manage orders.

## Base URL

```
https://api.khaime.com/api/v1
```

<Note>
  **Backwards Compatibility:** All Commerce API endpoints are also available at `/api/v1/*` for existing integrations. For example, both `/api/v1/products` and `/api/v1/products` work identically.
</Note>

## Authentication

All Commerce API endpoints require an API key passed in the `X-API-Key` header:

```bash theme={null}
curl https://api.khaime.com/api/v1/products \
  -H "X-API-Key: pk_live_your_api_key"
```

The API key identifies your business and scopes all responses to your products and customers.

## Endpoints

### Catalog

| Method | Endpoint       | Description          |
| ------ | -------------- | -------------------- |
| GET    | `/products`    | List all products    |
| GET    | `/product/:id` | Get a single product |

### Authentication

| Method | Endpoint    | Description             |
| ------ | ----------- | ----------------------- |
| POST   | `/register` | Register a new customer |
| POST   | `/login`    | Customer login          |

### Checkout

| Method | Endpoint                | Description               |
| ------ | ----------------------- | ------------------------- |
| POST   | `/coupon/validate`      | Validate a coupon code    |
| POST   | `/cart/validate`        | Build and validate cart   |
| POST   | `/cart-payment/preview` | Preview payment breakdown |
| POST   | `/payment/intent`       | Create payment intent     |

### Orders

| Method | Endpoint     | Description                  |
| ------ | ------------ | ---------------------------- |
| GET    | `/orders`    | Get customer's order history |
| GET    | `/order/:id` | Get order details            |

## Checkout Flow

```mermaid theme={null}
sequenceDiagram
    participant Frontend
    participant API
    participant Gateway

    Frontend->>API: POST /cart/validate
    API-->>Frontend: cart_unique_id + totals

    Frontend->>API: POST /payment/intent
    API->>Gateway: Create PaymentIntent
    Gateway-->>API: client_secret
    API-->>Frontend: client_secret

    Frontend->>Gateway: Confirm payment
    Gateway-->>Frontend: Payment complete

    Frontend->>API: GET /order/:id
    API-->>Frontend: Order confirmation
```

## Customer Authentication

For endpoints that require customer authentication (like `/orders`), include the customer token in the `Authorization` header:

```bash theme={null}
curl https://api.khaime.com/api/v1/orders \
  -H "X-API-Key: pk_live_your_api_key" \
  -H "Authorization: Bearer customer_token_here"
```

## Error Handling

All errors return a consistent JSON structure:

```json theme={null}
{
  "status": false,
  "message": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE"
}
```

Common error codes:

* `PRODUCT_NOT_FOUND` - Product doesn't exist
* `VALIDATION_FAILED` - Invalid request data
* `AUTH_TOKEN_EXPIRED` - Customer token expired
* `INTERNAL_ERROR` - Server error