---
title: "Create Checkout Session"
method: POST
path: "/v1/shops/{shopId}/checkout"
tags: ["Checkout"]
---

# Create Checkout Session

`POST /v1/shops/{shopId}/checkout`

Creates a checkout session (invoice) server-side and returns the URL to send the buyer to. Requires an API key; call it from your backend, never from a browser. Cart items are either <b>catalog items</b> (<code>productId</code> + <code>variantId</code>) or <b>custom items</b> (<code>name</code> + <code>price</code>, for one-off charges that are not in your catalog); both kinds can be mixed. If you pass both <code>email</code> and a payment method, the invoice is created as <code>pending</code> and a payment session is started immediately, so the returned <code>url</code> goes straight to the payment provider; otherwise it opens the hosted checkout where the buyer completes those steps. Available on plans with the Checkout API feature.

## Request body

- object
  - `cart` object[], required — The cart items. Each item is either a <b>catalog item</b> (<code>productId</code> + <code>variantId</code>) or a <b>custom item</b> (<code>name</code> + <code>price</code>). Both kinds can be mixed in one cart.
    - `productId` integer — Catalog item: the product ID. Shown when viewing the product in the dashboard. Omit for custom items.
    - `variantId` integer — Catalog item: the variant ID. Shown when editing the product in the dashboard. Omit for custom items.
    - `name` string — Custom item: the item name shown on the checkout and invoice. Requires <code>price</code>; not needed for catalog items. Must not be greater than 255 characters.
    - `price` number — Custom item: unit price in the checkout currency. Requires <code>name</code>; not needed for catalog items. Must be at least 0.
    - `quantity` integer, required — The quantity of the item. Must be at least 1. Must not be greater than 100000.
    - `subscribe` boolean — For subscription-enabled variants: start a recurring subscription instead of a one-time purchase.
    - `custom_fields` object — Values for the product's custom fields, keyed by field name.
  - `currency` string — ISO 4217 currency code. <b>Required when every cart item is a custom item</b>; otherwise inferred from the products. Must be 3 characters.
  - `ip` string — The end buyer's IP address. Defaults to the caller's IP; forward the buyer's IP when calling from your backend so fraud checks and analytics see the real buyer. Must be a valid IP address.
  - `country_code` string — The end buyer's ISO 3166-1 alpha-2 country code. Must contain only letters. Must be 2 characters.
  - `user_agent` string — The end buyer's user agent. Defaults to the caller's user agent.
  - `asn` integer — The end buyer's autonomous system number, if you have it.
  - `email` string — Prefill the customer email. When both <code>email</code> and a payment method are provided, the invoice is created as <code>pending</code> and a payment session is started immediately.
  - `discord_user_id` string — Internal: link the customer's Discord account.
  - `discord_user_username` string — Internal: link the customer's Discord account.
  - `discord_access_token` string — Internal: link the customer's Discord account.
  - `discord_refresh_token` string — Internal: link the customer's Discord account.
  - `coupon` string — A coupon code to apply.
  - `gateway` string — DEPRECATED, use <code>payment_method_id</code>. The payment gateway type to preselect. One of <code>STRIPE</code>, <code>SQUARE</code>, <code>SUMUP</code>, <code>MOLLIE</code>, <code>SKRILL</code>, <code>AUTHORIZENET</code>, <code>REVOLUTBUSINESS</code>, <code>LEMONSQUEEZY</code>, <code>NMI</code>, <code>OVERPAY</code>, <code>MONEI</code>, <code>RAZORPAY</code>, <code>PANDABASE</code>, <code>VENPAYR</code>, <code>OVGC</code>, <code>ADYEN</code>, <code>SHOPIFY</code>, <code>AMAZONPS</code>, <code>PAYCEK</code>, <code>PAYPAL</code>, <code>PAYPALFF</code>, <code>CASHAPP</code>, <code>VENMO</code>, <code>REWARBLE</code>, <code>BTC</code>, <code>LTC</code>. <code>CUSTOMERBALANCE</code> is not allowed on this endpoint.
  - `payment_method_id` integer — The payment method to preselect. Shown in the URL when editing a payment method in the dashboard. When set together with <code>email</code>, a payment session is started immediately and the response <code>url</code> points to the payment page.
  - `newsletter` boolean — Subscribe the customer to the shop newsletter.
  - `affiliate` string — An affiliate code to credit for this sale. Must not be greater than 16 characters.
  - `billing_name` string — Prefill: billing name. Must not be greater than 100 characters.
  - `billing_address_line1` string — Prefill: billing address line 1. Must not be greater than 150 characters.
  - `billing_address_line2` string — Prefill: billing address line 2. Must not be greater than 150 characters.
  - `billing_city` string — Prefill: billing city. Must not be greater than 100 characters.
  - `billing_state` string — Prefill: billing state or region. Must not be greater than 100 characters.
  - `billing_postcode` string — Prefill: billing postcode. Must not be greater than 20 characters.
  - `billing_country` string — Prefill: billing country (ISO 3166-1 alpha-2). Must be 2 characters.
  - `shipping_name` string — Prefill: shipping name. Must not be greater than 100 characters.
  - `shipping_address_line1` string — Prefill: shipping address line 1. Must not be greater than 150 characters.
  - `shipping_address_line2` string — Prefill: shipping address line 2. Must not be greater than 150 characters.
  - `shipping_city` string — Prefill: shipping city. Must not be greater than 100 characters.
  - `shipping_state` string — Prefill: shipping state or region. Must not be greater than 100 characters.
  - `shipping_postcode` string — Prefill: shipping postcode. Must not be greater than 20 characters.
  - `shipping_country` string — Prefill: shipping country (ISO 3166-1 alpha-2). Must be 2 characters.
  - `shipping_phone` string — Prefill: shipping phone number. Must not be greater than 20 characters.
  - `metadata` string[] — Must not be greater than 255 characters.

## Response `200`

Without a preselected payment method: url opens the hosted checkout

- object
  - `success` boolean
  - `invoice_id` integer
  - `invoice_url` string
  - `url` string

## Other responses

- `403`
- `422`

---

[API](https://skmtc.dev/sellauth/apis/sellauth-api.md) · [All operations](https://skmtc.dev/sellauth/apis/sellauth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sellauth/sellauth-api/revisions/945e6d749d68/schema)