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

# Checkout API

> Create checkout sessions server-side, including custom items not in your catalog.

The Checkout API is the full-code way to sell: your backend creates a checkout session and receives a URL to send the buyer to. Use it when [checkout links](/developers/checkout-links) (no code) or the [checkout embed](/developers/embed) (low code) are not flexible enough, for example to charge for one-off custom orders, prefill buyer details, or preselect a payment method.

<Note>Requires an API key ([**Account > Developers**](https://dash.sellauth.com/api) in the dashboard) and a plan with the Checkout API feature. Call it from your backend only; never expose your API key in a browser.</Note>

## Create a session

One endpoint: `POST /v1/shops/{shopId}/checkout`. Full parameter list and playground: [Create Checkout Session](/api-reference/checkout/create-checkout-session).

```bash theme={null}
curl -X POST https://api.sellauth.com/v1/shops/1/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": [
      { "productId": 1, "variantId": 1, "quantity": 1 }
    ]
  }'
```

Response:

```json theme={null}
{
  "success": true,
  "invoice_id": 3,
  "invoice_url": "https://demo-shop.sellauth.com/checkout/98b3f45d848c5-0000000000003",
  "url": "https://demo-shop.sellauth.com/checkout/98b3f45d848c5-0000000000003"
}
```

Redirect the buyer to `url`. Without a preselected payment method it opens the hosted checkout; with `email` + a payment method it goes straight to the payment provider (see below).

## Cart items

Each cart item is one of two kinds, and both kinds can be mixed in one cart:

<Tabs>
  <Tab title="Catalog item">
    References a product you sell. Stock, delivery, and pricing come from the catalog.

    ```json theme={null}
    { "productId": 1, "variantId": 1, "quantity": 2 }
    ```
  </Tab>

  <Tab title="Custom item">
    A one-off charge that does not exist in your catalog: commissions, invoicing a client, price-on-request orders. You set the name and unit price directly.

    ```json theme={null}
    { "name": "Custom order", "price": 49.99, "quantity": 1 }
    ```

    When **every** item in the cart is custom, `currency` is required at the top level:

    ```json theme={null}
    {
      "cart": [{ "name": "Design work", "price": 150, "quantity": 1 }],
      "currency": "USD"
    }
    ```
  </Tab>
</Tabs>

Per-item extras: `custom_fields` (values for the product's custom fields, keyed by field name) and `subscribe` (start a subscription on subscription-enabled variants).

## Skipping checkout steps

Provide what you already know and the buyer will not be asked for it:

```json theme={null}
{
  "cart": [{ "productId": 1, "variantId": 1, "quantity": 1 }],
  "email": "customer@example.com",
  "payment_method_id": 1,
  "coupon": "SAVE10"
}
```

With both `email` and a payment method (`payment_method_id`, or the deprecated `gateway` type), the invoice is created as `pending` and a payment session starts immediately: the returned `url` points directly to the payment provider (Stripe, PayPal, a crypto payment page, and so on).

Also accepted: billing and shipping address fields (`billing_*`, `shipping_*`), an `affiliate` code to credit, `newsletter` opt-in, and buyer context you should forward from your backend (`ip`, `country_code`, `user_agent`) so fraud checks see the real buyer instead of your server.

## Metadata

Attach up to 10 string values; they are stored on the invoice and returned when you fetch it later:

```json theme={null}
{ "metadata": { "order_ref": "A-1001", "source": "mobile-app" } }
```

## Attribution

If your backend knows how the buyer arrived, forward it so the invoice carries the same campaign data your storefront orders get. Keys are `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` and `referrer_host` (host only, no path), each at most 100 characters:

```json theme={null}
{ "attribution": { "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "spring_sale" } }
```

## After the sale

Track payment and delivery with [HTTP notifications](/developers/http-notifications), or poll [Get Invoice](/api-reference/invoices/get-invoice) with the returned `invoice_id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.