Sessions v1

Heads up: Sessions v1 is the legacy version of the Sessions API and is maintained for existing integrations only. If you're starting a new integration, use the current Sessions API. The current API exposes dedicated endpoints for managing cart items and customer details independently, giving you finer control over the checkout flow without replacing the full session payload on every update.

Use the Sessions v1 API to create custom order sessions and pass pre-configured cart data to your checkout before a buyer checks out. Sessions let you apply coupons, override product pricing, attach custom tags, and pre-fill customer details — all server-side, before the buyer sees the page.

Once created, a session returns a session ID you use to route the buyer directly into a pre-filled checkout. For base URL, authentication, technical standards, and observability, see the API overview.

API reference

The Sessions v1 API exposes a single endpoint for creating order sessions. Select it below to view request parameters and response schemas.

Create session

Create a custom order session with product items, pricing overrides, coupons, tags, and customer details.

Session configuration

A session request supports several optional configurations. These can be combined in a single request.

Customer identification

Identify the buyer using one of two methods:

Account ID — Pass the FastSpring-generated account ID for an existing customer. FastSpring applies all account details to the session automatically.
Contact object — Pass inline contact information (name, email, company, phone, country, language) when an account ID is unavailable. If an account already exists for the provided email, FastSpring associates it with the session.

Note: Always include a country value in the contact object for new buyers. If omitted, FastSpring defaults to the United States and USD as the transaction currency.

Price overrides

Override catalog pricing for one or more items in the session by passing a pricing object on each item. You can override:

Unit price — Specify per-currency amounts using ISO 4217 currency codes (e.g., USD, EUR).
Trial behavior — Set a trial length in days, specify whether payment is collected during the trial (paymentCollected), and define whether the trial is paid or free (paidTrial).
Renewal logic — Control post-trial or post-term behavior using the renew field: auto, manual, opt-auto, or opt-manual.
Discounts — Apply percentage or flat discounts with discountType, discountDuration, and quantityDiscounts.

Coupons

Apply a discount code to the session order by passing a coupon field with a valid coupon code (not the coupon ID).

{
  "account": "abCdE1FGH2Hij3KLMnOpqR",
  "coupon": "10OFF",
  "items": [
    { "product": "basic-laptop", "quantity": 1 }
  ]
}

Tags and attributes

Attach metadata to the order or individual items using key-value pairs:

Order-level tags — Use the tags object to attach custom labels for categorization, reporting, or integration workflows.
Item-level attributes — Use the attributes object on any line item for product-specific metadata or segmentation logic.

Session expiration

Sessions are valid for 24 hours by default. To extend this window, pass an expiration value of up to 7 days.

{
  "account": "abCdE1FGH2Hij3KLMnOpqR",
  "expiration": 7,
  "items": [
    { "product": "prime-sub", "quantity": 1 }
  ]
}

Collect payment

After creating a session, use the returned session ID to route the buyer into a pre-filled checkout. The method depends on your checkout type.

Web checkout

Append /session/ and the session ID to your checkout URL:

https://yourstore.onfastspring.com/session/{sessionId}

Popup checkout

Pass the session ID into the fastspring.builder.checkout method to launch the pre-filled popup checkout.

Note: Customers cannot modify session data. FastSpring applies all session configuration automatically when the buyer selects a payment method.