Create session

post

https://api.fastspring.com/v2/checkouts/{checkoutPath}/sessions

Creates a new order session. Accepts customer details, line items, and custom pricing. Server-to-server authentication is required to modify specific restricted fields.

The 201 response includes the session id, a ready-to-use checkoutUrls.webcheckoutUrl to redirect the buyer, calculated cart totals, and a checkoutStatus indicating whether the session is ready for checkout.

📘
No follow-up GET required
Everything needed to launch the buyer into checkout — including the session ID — is returned directly in this response. Use checkoutUrls.webcheckoutUrl to redirect the buyer, or pass the id to your frontend integration.

Path Params

checkoutPath

string

required

The unique identifier for the checkout instance, in the format store-id/checkout-id (e.g., fastspring/main).

Note: Target a specific checkout path to route the session to a single buyer experience and ensure accurate pricing. Stores frequently run multiple checkout variations simultaneously.

Body Params

The primary request payload used to formulate a new order session.

locale

string

length ≤ 5

Set the language for the buyer's experience. Accepts standard 2-letter language codes (e.g., en). Defaults to the browser locale if omitted.

country

string

The 2-letter ISO country code defining the buyer's billing location. Inferred from buyerIp if omitted.

buyerIp

string

length ≤ 39

The IPv4 or IPv6 address of the buyer. Used to infer country and currency if they are omitted. When executing an authenticated server-to-server request, this field acts as an override.

live

boolean

Defaults to true

Indicate whether the session processes in live mode (true) or test mode (false).
Review the Test orders documentation to learn how to safely simulate the buyer experience using test credit cards.

Note: If the targeted checkout is set to 'test mode' in your checkout settings, this value automatically defaults to false regardless of what you pass in the request.

customer

object

Specifies the customer and billing information applied to the order session.

orderTags

object

A key-value map of custom metadata attached to the finalized order record. Requires an authenticated request.

cart

object

The collection of line items and applied promotions constituting the order session.

paymentMethodsOrder

array of objects

Dictates the explicit sorting order of payment methods presented to the buyer. Unsupported payment methods are automatically suppressed. Requires an authenticated request.

paymentMethodsOrder

hidePaymentMethods

array of objects

Explicitly filters the provided payment methods from the buyer's interface. Requires an authenticated request.

hidePaymentMethods

Responses

No follow-up GET required

201Successfully created the session.

400Bad request. Indicates missing required fields or invalid formatting.

401Unauthorized. Access is restricted due to invalid authentication or location settings.