Sign in

v1

latestOpenAPI 3.0.02026-07-2475182625.5 KB
Session

Create session

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

post/v2/checkouts/{checkoutPath}/sessions

Path parameters

checkoutPathstring 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.

Example:fastspring/main

Request body

localestring

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

countrystring

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

buyerIpstring

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.

liveboolean

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.

orderTagsobject

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

paymentMethodsOrderPaymentMethodType[]

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

hidePaymentMethodsPaymentMethodType[]

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

Example request

{
  "locale": "en",
  "country": "US",
  "buyerIp": "127.0.0.1",
  "live": true,
  "customer": {
    "accountId": "ABC1234567890",
    "externalAccountId": "EXT-98765",
    "billToContact": {
      "email": "support@fastspring.com",
      "firstName": "John",
      "lastName": "Doe",
      "company": "FastSpring",
      "phoneNumber": "555-555-5555"
    },
    "billToAddress": {
      "addressLine1": "801 Garden Street",
      "addressLine2": "suite 201",
      "city": "Santa Barbara",
      "region": "CA",
      "postalCode": "93101"
    },
    "shipToContact": {
      "email": "support@fastspring.com",
      "firstName": "John",
      "lastName": "Doe",
      "company": "FastSpring",
      "phoneNumber": "555-555-5555"
    },
    "shipToAddress": {
      "addressLine1": "801 Garden Street",
      "addressLine2": "suite 201",
      "city": "Santa Barbara",
      "region": "CA",
      "postalCode": "93101"
    },
    "shipToType": "SAME_AS_BILL_TO",
    "accountTags": {
      "customerType": "VIP"
    },
    "taxId": "DE123456789",
    "taxIdRegion": "CA"
  },
  "orderTags": {
    "campaign": "Q1_Social"
  },
  "cart": {
    "couponCode": "SUMMER_2026",
    "lineItems": [
      {
        "productPath": "gold-tier",
        "quantity": 1,
        "quantityBehavior": "ALLOW",
        "quantityDefault": 1,
        "descriptions": {
          "display": {
            "ar": "Arabic",
            "cs": "Czech",
            "da": "Danish",
            "de": "German",
            "es": "Spanish",
            "en": "English",
            "fi": "Finnish",
            "fr": "French",
            "hr": "Croatian",
            "it": "Italian",
            "iw": "Hebrew",
            "ja": "Japanese",
            "ko": "Korean",
            "nl": "Dutch",
            "no": "Norwegian",
            "pl": "Polish",
            "pt": "Portuguese",
            "ru": "Russian",
            "sk": "Slovak",
            "sv": "Swedish",
            "tr": "Turkish",
            "zh": "Chinese"
          },
          "instructions": {
            "ar": "Arabic",
            "cs": "Czech",
            "da": "Danish",
            "de": "German",
            "es": "Spanish",
            "en": "English",
            "fi": "Finnish",
            "fr": "French",
            "hr": "Croatian",
            "it": "Italian",
            "iw": "Hebrew",
            "ja": "Japanese",
            "ko": "Korean",
            "nl": "Dutch",
            "no": "Norwegian",
            "pl": "Polish",
            "pt": "Portuguese",
            "ru": "Russian",
            "sk": "Slovak",
            "sv": "Swedish",
            "tr": "Turkish",
            "zh": "Chinese"
          },
          "summary": {
            "ar": "Arabic",
            "cs": "Czech",
            "da": "Danish",
            "de": "German",
            "es": "Spanish",
            "en": "English",
            "fi": "Finnish",
            "fr": "French",
            "hr": "Croatian",
            "it": "Italian",
            "iw": "Hebrew",
            "ja": "Japanese",
            "ko": "Korean",
            "nl": "Dutch",
            "no": "Norwegian",
            "pl": "Polish",
            "pt": "Portuguese",
            "ru": "Russian",
            "sk": "Slovak",
            "sv": "Swedish",
            "tr": "Turkish",
            "zh": "Chinese"
          },
          "imageUrl": "https://cdn.onfastspring.com/themes/images/default-store-logo.png"
        },
        "customPrice": {
          "unitPrice": {
            "AED": 10,
            "ARS": 10,
            "AUD": 10,
            "BRL": 10,
            "CAD": 10,
            "CHF": 10,
            "CLP": 10,
            "CNY": 10,
            "COP": 10,
            "CZK": 10,
            "DKK": 10,
            "EUR": 10,
            "GBP": 10,
            "HKD": 10,
            "HUF": 10,
            "IDR": 10,
            "INR": 10,
            "JPY": 10,
            "KRW": 10,
            "MXN": 10,
            "MYR": 10,
            "NOK": 10,
            "NZD": 10,
            "PEN": 10,
            "PHP": 10,
            "PLN": 10,
            "RUB": 10,
            "SAR": 10,
            "SEK": 10,
            "SGD": 10,
            "THB": 10,
            "TRY": 10,
            "TWD": 10,
            "USD": 10,
            "VND": 10,
            "ZAR": 10
          },
          "discounts": [
            {
              "minQuantity": 2,
              "amountDiscount": {
                "AED": 10,
                "ARS": 10,
                "AUD": 10,
                "BRL": 10,
                "CAD": 10,
                "CHF": 10,
                "CLP": 10,
                "CNY": 10,
                "COP": 10,
                "CZK": 10,
                "DKK": 10,
                "EUR": 10,
                "GBP": 10,
                "HKD": 10,
                "HUF": 10,
                "IDR": 10,
                "INR": 10,
                "JPY": 10,
                "KRW": 10,
                "MXN": 10,
                "MYR": 10,
                "NOK": 10,
                "NZD": 10,
                "PEN": 10,
                "PHP": 10,
                "PLN": 10,
                "RUB": 10,
                "SAR": 10,
                "SEK": 10,
                "SGD": 10,
                "THB": 10,
                "TRY": 10,
                "TWD": 10,
                "USD": 10,
                "VND": 10,
                "ZAR": 10
              },
              "percentDiscount": 10
            }
          ],
          "discountDuration": 3,
          "setupFee": {
            "AED": 10,
            "ARS": 10,
            "AUD": 10,
            "BRL": 10,
            "CAD": 10,
            "CHF": 10,
            "CLP": 10,
            "CNY": 10,
            "COP": 10,
            "CZK": 10,
            "DKK": 10,
            "EUR": 10,
            "GBP": 10,
            "HKD": 10,
            "HUF": 10,
            "IDR": 10,
            "INR": 10,
            "JPY": 10,
            "KRW": 10,
            "MXN": 10,
            "MYR": 10,
            "NOK": 10,
            "NZD": 10,
            "PEN": 10,
            "PHP": 10,
            "PLN": 10,
            "RUB": 10,
            "SAR": 10,
            "SEK": 10,
            "SGD": 10,
            "THB": 10,
            "TRY": 10,
            "TWD": 10,
            "USD": 10,
            "VND": 10,
            "ZAR": 10
          },
          "edsFee": {
            "AED": 10,
            "ARS": 10,
            "AUD": 10,
            "BRL": 10,
            "CAD": 10,
            "CHF": 10,
            "CLP": 10,
            "CNY": 10,
            "COP": 10,
            "CZK": 10,
            "DKK": 10,
            "EUR": 10,
            "GBP": 10,
            "HKD": 10,
            "HUF": 10,
            "IDR": 10,
            "INR": 10,
            "JPY": 10,
            "KRW": 10,
            "MXN": 10,
            "MYR": 10,
            "NOK": 10,
            "NZD": 10,
            "PEN": 10,
            "PHP": 10,
            "PLN": 10,
            "RUB": 10,
            "SAR": 10,
            "SEK": 10,
            "SGD": 10,
            "THB": 10,
            "TRY": 10,
            "TWD": 10,
            "USD": 10,
            "VND": 10,
            "ZAR": 10
          },
          "shippingFee": {
            "AED": 10,
            "ARS": 10,
            "AUD": 10,
            "BRL": 10,
            "CAD": 10,
            "CHF": 10,
            "CLP": 10,
            "CNY": 10,
            "COP": 10,
            "CZK": 10,
            "DKK": 10,
            "EUR": 10,
            "GBP": 10,
            "HKD": 10,
            "HUF": 10,
            "IDR": 10,
            "INR": 10,
            "JPY": 10,
            "KRW": 10,
            "MXN": 10,
            "MYR": 10,
            "NOK": 10,
            "NZD": 10,
            "PEN": 10,
            "PHP": 10,
            "PLN": 10,
            "RUB": 10,
            "SAR": 10,
            "SEK": 10,
            "SGD": 10,
            "THB": 10,
            "TRY": 10,
            "TWD": 10,
            "USD": 10,
            "VND": 10,
            "ZAR": 10
          }
        },
        "attributes": {
          "licenseKey": "ABC-123"
        },
        "subscriptionOverrides": {
          "billingFrequency": {
            "intervalUnit": "MONTH",
            "intervalLength": 1,
            "intervalCount": 1
          },
          "trialDays": 14
        }
      }
    ]
  },
  "paymentMethodsOrder": [
    "CARD",
    "PAYPAL"
  ],
  "hidePaymentMethods": [
    "WIRE"
  ]
}

Response

Successfully created the session.

idstring

The unique primary identifier representing the established session.

createdstring date-time

The ISO 8601 timestamp marking the exact moment the session was initialized.

expiresstring date-time

The ISO 8601 timestamp marking when the session data expires and requires recreation.

status'OPEN' | 'EXPIRED' | 'CANCELLED' | 'PENDING_ORDER' | 'COMPLETED' | 'FAILED'

Describes the current lifecycle phase of the session.

localestring

The display language code currently applied to the session formatting.

countrystring

The 2-letter ISO country code denoting the buyer's billing location utilized for localized pricing.

currencystring

The active currency code utilized for all pricing calculations.

liveboolean

Indicates true if the session is currently transacting real funds against live merchant accounts.

orderTagsobject

A key-value map of custom metadata configured to attach to the finalized order record.

checkoutStatusstring[]

Indicates the current rendering state of the checkout session.

  • READY_FOR_CHECKOUT: The session is fully populated and capable of processing.
  • PRODUCTS_REQUIRED: The checkout cannot render because no products have been added to the session.
  • CONCLUDED: The checkout session has been finalized.

Example response

{
  "id": "OS123456789012345ABC",
  "created": "2026-03-20T10:49:51.000Z",
  "expires": "2026-03-21T10:49:51.000Z",
  "status": "OPEN",
  "locale": "en",
  "country": "US",
  "currency": "USD",
  "live": true,
  "customer": {
    "accountId": "ABC1234567890",
    "externalAccountId": "EXT-98765",
    "savedPaymentMethod": {
      "paymentMethodType": "CARD",
      "display": "VISA - 4242"
    },
    "billToContact": {
      "email": "support@fastspring.com",
      "firstName": "John",
      "lastName": "Doe",
      "company": "FastSpring",
      "phoneNumber": "555-555-5555"
    },
    "billToAddress": {
      "addressLine1": "801 Garden Street",
      "addressLine2": "suite 201",
      "city": "Santa Barbara",
      "region": "CA",
      "postalCode": "93101"
    },
    "shipToContact": {
      "email": "support@fastspring.com",
      "firstName": "John",
      "lastName": "Doe",
      "company": "FastSpring",
      "phoneNumber": "555-555-5555"
    },
    "shipToAddress": {
      "addressLine1": "801 Garden Street",
      "addressLine2": "suite 201",
      "city": "Santa Barbara",
      "region": "CA",
      "postalCode": "93101"
    },
    "accountTags": {
      "customerType": "VIP"
    },
    "taxId": "DE123456789",
    "taxIdRegion": "CA"
  },
  "orderTags": {
    "campaign": "Q1_Social"
  },
  "cart": {
    "couponCode": "10_OFF",
    "couponHasApplied": true,
    "lineItems": [
      {
        "productPath": "gold-tier",
        "quantity": 2,
        "quantityBehavior": "ALLOW",
        "quantityDefault": 1,
        "price": {
          "unitNetPrice": 90,
          "unitNetPriceDisplay": "$90.00",
          "unitListPrice": 100,
          "unitListPriceDisplay": "$100.00",
          "unitDiscount": 10,
          "unitDiscountDisplay": "$10.00",
          "extendedTotalDiscount": 20,
          "extendedTotalDiscountDisplay": "$20.00",
          "extendedNetTotal": 180,
          "extendedNetTotalDisplay": "$180.00",
          "extendedListTotal": 200,
          "extendedListTotalDisplay": "$200.00",
          "taxIncluded": "TAXES_INCLUDED_IN_PRICE",
          "unitTaxAmount": 10,
          "unitTaxAmountDisplay": "$10.00",
          "extendedTaxTotal": 20,
          "extendedTaxTotalDisplay": "$20.00",
          "taxPercent": 10,
          "productDiscountDuration": 100,
          "couponDiscountDuration": 100
        },
        "productType": "ONE_TIME",
        "removable": true,
        "descriptions": {
          "display": {
            "ar": "Arabic",
            "cs": "Czech",
            "da": "Danish",
            "de": "German",
            "es": "Spanish",
            "en": "English",
            "fi": "Finnish",
            "fr": "French",
            "hr": "Croatian",
            "it": "Italian",
            "iw": "Hebrew",
            "ja": "Japanese",
            "ko": "Korean",
            "nl": "Dutch",
            "no": "Norwegian",
            "pl": "Polish",
            "pt": "Portuguese",
            "ru": "Russian",
            "sk": "Slovak",
            "sv": "Swedish",
            "tr": "Turkish",
            "zh": "Chinese"
          },
          "instructions": {
            "ar": "Arabic",
            "cs": "Czech",
            "da": "Danish",
            "de": "German",
            "es": "Spanish",
            "en": "English",
            "fi": "Finnish",
            "fr": "French",
            "hr": "Croatian",
            "it": "Italian",
            "iw": "Hebrew",
            "ja": "Japanese",
            "ko": "Korean",
            "nl": "Dutch",
            "no": "Norwegian",
            "pl": "Polish",
            "pt": "Portuguese",
            "ru": "Russian",
            "sk": "Slovak",
            "sv": "Swedish",
            "tr": "Turkish",
            "zh": "Chinese"
          },
          "summary": {
            "ar": "Arabic",
            "cs": "Czech",
            "da": "Danish",
            "de": "German",
            "es": "Spanish",
            "en": "English",
            "fi": "Finnish",
            "fr": "French",
            "hr": "Croatian",
            "it": "Italian",
            "iw": "Hebrew",
            "ja": "Japanese",
            "ko": "Korean",
            "nl": "Dutch",
            "no": "Norwegian",
            "pl": "Polish",
            "pt": "Portuguese",
            "ru": "Russian",
            "sk": "Slovak",
            "sv": "Swedish",
            "tr": "Turkish",
            "zh": "Chinese"
          },
          "imageUrl": "https://cdn.onfastspring.com/themes/images/default-store-logo.png"
        },
        "productFormat": "DIGITAL",
        "attributes": {
          "licenseKey": "ABC-123"
        },
        "subscription": {
          "billingFrequency": {
            "intervalUnit": "MONTH",
            "intervalLength": 1,
            "intervalCount": 1
          },
          "trialDays": 14
        }
      }
    ],
    "netTotal": 90,
    "netTotalDisplay": "$90.00",
    "listTotal": 100,
    "listTotalDisplay": "$100.00",
    "withTaxNetTotal": 90,
    "withTaxNetTotalDisplay": "$90.00",
    "withTaxListTotal": 100,
    "withTaxListTotalDisplay": "$100.00",
    "withoutTaxNetTotal": 70,
    "withoutTaxNetTotalDisplay": "$70.00",
    "withoutTaxListTotal": 80,
    "withoutTaxListTotalDisplay": "$80.00",
    "discountTotal": 10,
    "discountTotalDisplay": "$10.00",
    "couponDiscountTotal": 10,
    "couponDiscountTotalDisplay": "$10.00",
    "productDiscountTotalDisplay": "$0.00",
    "taxIncluded": "TAXES_INCLUDED_IN_PRICE",
    "taxTotal": 20,
    "taxTotalDisplay": "$20.00",
    "taxRate": 28.57
  },
  "checkoutUrls": {
    "webcheckoutUrl": "https://example.onfastspring.com/checkout/session/OS123456789012345ABC"
  },
  "warnings": [
    {
      "code": "INVALID_PROMO_CODE",
      "field": "promoCode",
      "message": "The promo code you entered is invalid and was not applied. Please check the code."
    }
  ],
  "checkoutStatus": [
    "PRODUCTS_REQUIRED"
  ]
}