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

# Start Checkout

> Create a draft order from a storefront cart.

```bash theme={null}
POST /api/checkout/start
```

Primary path for Vite storefronts (`platform-checkout.ts`). Creates a **draft** order and returns an id you open at `/checkout/{orderId}`.

## Rate limit

**15 requests / 60 seconds** per client → `429`.

## Body

```json theme={null}
{
  "subdomain": "acme",
  "cart": [
    {
      "id": "PRODUCT_CUID",
      "name": "Pro License",
      "price": 29.99,
      "quantity": 1,
      "image": null
    }
  ],
  "subtotal": 29.99,
  "discount": 0,
  "referralCode": null,
  "clientPublicIp": null
}
```

<ParamField body="subdomain" type="string" required>
  Store subdomain.
</ParamField>

<ParamField body="cart" type="array" required>
  At least one line. Each line needs `id` or `productId`, plus `name`. Quantity/price/image optional.
</ParamField>

<ParamField body="orderId" type="string">
  Optional pre-allocated checkout order id (must pass `isValidCheckoutOrderId`).
</ParamField>

<ParamField body="referralCode" type="string">
  Affiliate / referral code.
</ParamField>

## Response `200`

```json theme={null}
{
  "orderId": "clxxxxxxxx",
  "order": {
    "orderId": "clxxxxxxxx",
    "storeId": "…",
    "productName": "Pro License",
    "price": 29.99,
    "status": "processing"
  }
}
```

Navigate the buyer to `/checkout/{orderId}` on the **app origin**.

## Related

| Endpoint                         | Role                                                              |
| -------------------------------- | ----------------------------------------------------------------- |
| `POST /api/checkout/client-gate` | VPN / anti-fraud probe (30/min)                                   |
| `POST /api/checkout/session`     | Set access cookie from token                                      |
| `GET /api/checkout/enter`        | Cookie + redirect helper                                          |
| `POST /api/v1/checkout`          | Nunjucks / SellAuth-style `{ shopId, cart }` → `{ url, orderId }` |

## Notes

* Same-origin from the storefront is the expected caller. This is not CORS-opened like embed checkout.
* Prefer this over inventing orders in the client — stock, holds, and pricing are resolved server-side in `startCheckout`.
* Embed merchants should use [`POST /api/embed/checkout`](/api/embed-checkout) instead; it builds the cart from product ids and returns an embed URL with `?embed=1`.