Sign in
Checkout

Create Checkout Session

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.

post/v1/shops/{shopId}/checkout

Request body

currencystring

ISO 4217 currency code. <b>Required when every cart item is a custom item</b>; otherwise inferred from the products. Must be 3 characters.

ipstring

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_codestring

The end buyer's ISO 3166-1 alpha-2 country code. Must contain only letters. Must be 2 characters.

user_agentstring

The end buyer's user agent. Defaults to the caller's user agent.

asninteger

The end buyer's autonomous system number, if you have it.

emailstring

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_idstring

Internal: link the customer's Discord account.

discord_user_usernamestring

Internal: link the customer's Discord account.

discord_access_tokenstring

Internal: link the customer's Discord account.

discord_refresh_tokenstring

Internal: link the customer's Discord account.

couponstring

A coupon code to apply.

gatewaystring

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_idinteger

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.

newsletterboolean

Subscribe the customer to the shop newsletter.

affiliatestring

An affiliate code to credit for this sale. Must not be greater than 16 characters.

billing_namestring

Prefill: billing name. Must not be greater than 100 characters.

billing_address_line1string

Prefill: billing address line 1. Must not be greater than 150 characters.

billing_address_line2string

Prefill: billing address line 2. Must not be greater than 150 characters.

billing_citystring

Prefill: billing city. Must not be greater than 100 characters.

billing_statestring

Prefill: billing state or region. Must not be greater than 100 characters.

billing_postcodestring

Prefill: billing postcode. Must not be greater than 20 characters.

billing_countrystring

Prefill: billing country (ISO 3166-1 alpha-2). Must be 2 characters.

shipping_namestring

Prefill: shipping name. Must not be greater than 100 characters.

shipping_address_line1string

Prefill: shipping address line 1. Must not be greater than 150 characters.

shipping_address_line2string

Prefill: shipping address line 2. Must not be greater than 150 characters.

shipping_citystring

Prefill: shipping city. Must not be greater than 100 characters.

shipping_statestring

Prefill: shipping state or region. Must not be greater than 100 characters.

shipping_postcodestring

Prefill: shipping postcode. Must not be greater than 20 characters.

shipping_countrystring

Prefill: shipping country (ISO 3166-1 alpha-2). Must be 2 characters.

shipping_phonestring

Prefill: shipping phone number. Must not be greater than 20 characters.

metadatastring[]

Must not be greater than 255 characters.

Example request

{
  "cart": [
    {
      "productId": 1,
      "variantId": 1,
      "quantity": 1
    }
  ],
  "currency": "USD",
  "ip": "203.0.113.10",
  "country_code": "US",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "asn": 64496,
  "email": "customer@example.com",
  "coupon": "SAVE10",
  "gateway": "STRIPE",
  "payment_method_id": 1,
  "affiliate": "PARTNER10",
  "billing_name": "John Doe",
  "billing_address_line1": "123 Main St",
  "billing_address_line2": "Apt 4",
  "billing_city": "Springfield",
  "billing_state": "IL",
  "billing_postcode": "62701",
  "billing_country": "US",
  "shipping_name": "John Doe",
  "shipping_address_line1": "123 Main St",
  "shipping_address_line2": "Apt 4",
  "shipping_city": "Springfield",
  "shipping_state": "IL",
  "shipping_postcode": "62701",
  "shipping_country": "US",
  "shipping_phone": "+1 555 0100",
  "metadata": [
    "pasyzwszwtxpeqq"
  ]
}

Response

Without a preselected payment method: url opens the hosted checkout

successboolean
invoice_idinteger
invoice_urlstring
urlstring

Example 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"
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.