About the Checkout Sessions API

The Checkout Sessions API creates a Wix-hosted checkout session for a set of line items. Each call creates a fresh, single-use session tailored to that buyer and that cart.

With the Checkout Sessions API, you can:

• Create a Wix-hosted checkout session for one-time or subscription line items.
• Pre-fill the checkout form with known buyer details to reduce friction at payment.
• Configure recurring billing per line item, including frequency, billing cycles, and free trial period, currently limited to one line item per checkout session.

About line items

A line item can be a one-time charge or a subscription. Subscription line items trigger recurring billing on a schedule you configure.

Submitted line items and their configuration are locked on the Wix-hosted checkout page: buyers can pay, but they can't change the cart.

subscriptionInfo covers more than just recurring billing:

• With subscriptionSettings.billingCycles: 1, you can model "free trial then a single charge": a free trial period followed by 1 paid charge at the end.
• With billingCycles greater than 1, the subscription runs for a fixed number of cycles and then stops.
• With billingCycles omitted, the subscription renews indefinitely.

One-time items can be combined with a single subscription item. In that case the buyer is charged once at checkout for the one-time items and, if applicable, the first cycle of the subscription. Wix bills any subsequent cycles on the subscription's own schedule.

Before you begin

It's important to note the following points before starting to code:

• At most 1 subscription line item (an item with subscriptionInfo set) is allowed per request. Wix rejects requests with 2 or more subscription items. For how subscription items combine with one-time items, see Line items.
• Coupon codes and gift cards are disabled on the Wix-hosted checkout page. Buyers can edit only their buyer-info fields: name, email, phone, and address.
• Pass checkoutSession.redirectUrl through to the buyer unchanged. The URL carries query parameters Wix needs to render the page correctly. For example, successUrl is forwarded as a query parameter from callbackUrls.thankYouPageUrl. Stripping or rewriting query parameters breaks the buyer-facing flow.
• Callback URLs (callbackUrls.continueBrowsingUrl, callbackUrls.thankYouPageUrl) must be absolute, publicly reachable HTTPS URLs. Wix doesn't synchronously verify them at session generation. An unreachable URL surfaces only when the buyer is redirected, at which point the buyer reaches a broken destination. Validate URLs on your side before passing them in.
• Generate Checkout Session isn't idempotent. Every successful call creates a new checkout session. Track the returned checkoutSession.id against the buyer record on your side and avoid blind retries on transient failures.

Terminology

• Checkout session: A Wix-hosted checkout page generated for a specific set of line items. The Generate Checkout Session response returns its redirectUrl (where the buyer is sent to pay) and its id (the session identifier, generated by the call).
• Line item: A single product, service, or subscription the buyer is paying for in a checkout session.
• Subscription line item: A line item with subscriptionInfo set. Triggers recurring billing instead of a single charge.
• Callback URLs: The URLs the buyer is redirected to after the checkout flow. continueBrowsingUrl is used if they leave the Wix checkout page without paying (clicking Continue browsing or navigating back to a cart-style page); thankYouPageUrl is used after a successful payment.