Checkout API

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 (no code) or the checkout embed (low code) are not flexible enough, for example to charge for one-off custom orders, prefill buyer details, or preselect a payment method.

Requires an API key (Account > Developers 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.

Create a session

One endpoint: POST /v1/shops/{shopId}/checkout. Full parameter list and playground: Create Checkout Session.

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:

{
  "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:

Catalog item
Custom item

References a product you sell. Stock, delivery, and pricing come from the catalog.

{ "productId": 1, "variantId": 1, "quantity": 2 }

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.

{ "name": "Custom order", "price": 49.99, "quantity": 1 }

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

{
  "cart": [{ "name": "Design work", "price": 150, "quantity": 1 }],
  "currency": "USD"
}

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:

{
  "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:

{ "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:

{ "attribution": { "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "spring_sale" } }

After the sale

Track payment and delivery with HTTP notifications, or poll Get Invoice with the returned invoice_id.

Storefront

Integrations

Theming

Localization

Create a session

Cart items

Skipping checkout steps

Metadata

Attribution

After the sale

​Create a session

​Cart items

​Skipping checkout steps

​Metadata

​Attribution

​After the sale

Create a session

Cart items

Skipping checkout steps

Metadata

Attribution

After the sale