Sessions

Use the Sessions API to programmatically create and manage checkout sessions, passing pre-filled cart and customer data directly to your storefront before the buyer ever sees the page.

The Sessions API exposes dedicated endpoints for managing individual cart items and customer details — enabling dynamic checkout flows without replacing the entire session payload. For base URL, authentication, technical standards, and observability, see the API overview.

Note: Maintaining an existing integration on the legacy API? See the Sessions v1 reference. All new integrations should use the current Sessions API documented here.

API reference

The Sessions API is organized around the order session lifecycle — from creation to cart management and customer updates. Select an endpoint below to view its request parameters, path variables, and response schemas.

Create session

Create a new order session with pre-filled cart items, customer details, and optional custom pricing.

Retrieve session

Retrieve the complete details and current state of an existing order session.

Update session

Overwrite customer details, items, and custom pricing on an existing session.

Retrieve payment methods

Retrieve the localized, filtered list of payment methods available for a session.

Add session item

Append a new product item to the cart of an existing session.

Remove session item

Remove a specific product from the session cart by product path.

Update session item

Modify the quantity or custom pricing of one or more products in the session cart.

Update session customer

Update customer and billing information on an existing session without replacing the full payload.

Checkout path

Every Sessions API endpoint requires a checkoutPath as a path parameter. The checkout path identifies the target checkout instance and ensures sessions are created with the correct pricing, configuration, and buyer experience.

Checkout path format

The checkoutPath is composed of two segments separated by a single forward slash: {storeId}/{checkoutId}.

storeId — your FastSpring store identifier (for example, examplestore).
checkoutId — the identifier of a specific checkout configured in that store (for example, popup-checkout).

Combined, those values produce a checkoutPath of examplestore/popup-checkout, which slots into the request URL where {checkoutPath} appears:

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

With the example values above, the resolved URL is:

https://api.fastspring.com/v2/checkouts/examplestore/popup-checkout/sessions

How checkoutId is constructed

A checkoutId is generated by FastSpring when you create a checkout in your store, and it always follows the pattern {checkoutType}-{checkoutName}:

checkoutType — one of FastSpring's supported checkout types: popup, embedded, or web. This prefix is fixed by the platform based on the type of checkout you created — it is not a value you choose.
checkoutName — the name you gave the checkout when you created it (for example, checkout, dark-theme, default-template, holiday-promo).

Stores frequently run multiple checkout variations simultaneously, so always target the specific checkoutId for the experience you want to load — using the wrong one will return session data with the wrong pricing, locale, or layout configuration.