v1

latestOpenAPI 3.0.02026-07-2475182625.5 KB

Sessions

Create a session

Creates custom order sessions with various configurations, such as single product sessions, price overrides, coupons, and custom tags.

post/sessions

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

idstring

Unique identifier for the order session.

currencystring

Currency code for the order session. The currency you specify in the request payload is localized to match the session country's currency when applicable.

expiresinteger

Expiration timestamp for the order session in milliseconds since the Unix epoch. After this timestamp, the order session is no longer valid.

orderstring nullable

Identifier for the created order. If no order has been created yet, this field is null.

accountstring

Unique identifier for the account associated with the order session.

subtotalnumber float

Subtotal amount for the order session.

Example response

{
  "id": "gNFgV9ITTbyylJkiIhnmOQ",
  "currency": "USD",
  "expires": 1731469407156,
  "account": "abCdE1FGH2Hij3KLMnOpqR",
  "subtotal": 399.99,
  "items": [
    {
      "product": "basic-laptop",
      "quantity": 1
    }
  ]
}