--- title: "Create a session" method: POST path: "/sessions" tags: ["Sessions"] --- # Create a session `POST /sessions` Creates custom order sessions with various configurations, such as single product sessions, price overrides, coupons, and custom tags. ## Request body - CreateSessionRequest — The primary request payload used to formulate a new order session. - `locale` string — 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 — 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 — Indicate whether the session processes in live mode (`true`) or test mode (`false`). Review the [Test orders](https://developer.fastspring.com/docs/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` CustomerRequest — Specifies the customer and billing information applied to the order session. - `accountId` string — The unique identifier mapping the buyer to a FastSpring account. Requires an authenticated request. - `externalAccountId` string, regex — An external ID used to link the buyer to your internal systems. Requires an authenticated request. - `billToContact` BillToContact — Capture the billing contact details used to process the payment, calculate localized taxes, and generate the invoice. Pass standard, single-buyer information here, as this acts as the primary contact for the order. - `email` string — The buyer's email address. - `firstName` string — The buyer's first name. - `lastName` string — The buyer's last name. - `company` string — The name of the buyer's company. - `phoneNumber` string — The buyer's phone number. - `billToAddress` BillToAddress — Capture the physical address associated with the buyer's payment method for tax calculation and invoicing. - `addressLine1` string — The first line of the address, typically the street number and name. - `addressLine2` string — The second line of the address, typically an apartment, suite, or unit number. - `city` string — The city of the address. - `region` string — Provide the state or province. Use the 2-letter state or province code for the USA and Canada. Use the full region name for other countries. - `postalCode` string — The postal or ZIP code. - `shipToContact` ShipToContact — Capture the recipient's contact and delivery details to ensure accurate fulfillment. - `email` string — The buyer's email address. - `firstName` string — The buyer's first name. - `lastName` string — The buyer's last name. - `company` string — The name of the buyer's company. - `phoneNumber` string — The buyer's phone number. - `shipToAddress` ShipToAddress — Capture the physical destination address to ensure accurate delivery of shipped goods. - `addressLine1` string — The first line of the address, typically the street number and name. - `addressLine2` string — The second line of the address, typically an apartment, suite, or unit number. - `city` string — The city of the address. - `region` string — Provide the state or province. Use the 2-letter state or province code for the USA and Canada. Use the full region name for other countries. - `postalCode` string — The postal or ZIP code. - `shipToType` 'GIFT_PURCHASE' | 'SHIP_TO' | 'SAME_AS_BILL_TO' — Identifies the type of shipping destination mapping applied to the order. - `accountTags` object — A key-value map of custom tags applied to the buyer's account. Requires an authenticated request. - `taxId` string — Capture the buyer's VAT, GST, or CPF identification number used for tax calculation or exemption. Required for buyers located in Brazil. - `taxIdRegion` string — The 2-letter state or province code associated with a US tax exemption. - `orderTags` object — A key-value map of custom metadata attached to the finalized order record. Requires an authenticated request. - `cart` CartRequest — The collection of line items and applied promotions constituting the order session. - `couponCode` string — The promotional coupon code applied to the cart totals. - `lineItems` OrderItemRequest[] — A list of products populated in the session cart. - `productPath` string, required — The unique identifier of the catalog product to add. - `quantity` integer — The total volume of units to purchase. Defaults to 1 if omitted. - `quantityBehavior` string — Indicates whether the buyer is allowed to modify the item quantity during checkout. Requires an authenticated request. - `quantityDefault` integer — The default quantity presented at checkout. Requires an authenticated request. - `descriptions` ProductDescription — Specifies localized descriptive fields for a product. Requires an authenticated request to modify. - `display` LanguageMap — A map of localized strings based on ISO 639-1 language codes. - `ar` string - `cs` string - `da` string - `de` string - `es` string - `en` string - `fi` string - `fr` string - `hr` string - `it` string - `iw` string - `ja` string - `ko` string - `nl` string - `no` string - `pl` string - `pt` string - `ru` string - `sk` string - `sv` string - `tr` string - `zh` string - `instructions` LanguageMap — A map of localized strings based on ISO 639-1 language codes. - `ar` string - `cs` string - `da` string - `de` string - `es` string - `en` string - `fi` string - `fr` string - `hr` string - `it` string - `iw` string - `ja` string - `ko` string - `nl` string - `no` string - `pl` string - `pt` string - `ru` string - `sk` string - `sv` string - `tr` string - `zh` string - `summary` LanguageMap — A map of localized strings based on ISO 639-1 language codes. - `ar` string - `cs` string - `da` string - `de` string - `es` string - `en` string - `fi` string - `fr` string - `hr` string - `it` string - `iw` string - `ja` string - `ko` string - `nl` string - `no` string - `pl` string - `pt` string - `ru` string - `sk` string - `sv` string - `tr` string - `zh` string - `imageUrl` string — The absolute URL of the product's primary image. - `customPrice` object — Overrides the base catalog price with a custom defined pricing structure. Requires an authenticated request. - `unitPrice` PriceMap — A map of fixed prices across supported currencies. - `AED` number - `ARS` number - `AUD` number - `BRL` number - `CAD` number - `CHF` number - `CLP` number - `CNY` number - `COP` number - `CZK` number - `DKK` number - `EUR` number - `GBP` number - `HKD` number - `HUF` number - `IDR` number - `INR` number - `JPY` number - `KRW` number - `MXN` number - `MYR` number - `NOK` number - `NZD` number - `PEN` number - `PHP` number - `PLN` number - `RUB` number - `SAR` number - `SEK` number - `SGD` number - `THB` number - `TRY` number - `TWD` number - `USD` number - `VND` number - `ZAR` number - `discounts` object[] — A list of volume-based discounting tiers. Applicable ranges must not overlap. - `minQuantity` integer — The minimum volume of units required to trigger this discount tier. Defaults to `1`. - `amountDiscount` PriceMap — A map of fixed prices across supported currencies. - `AED` number - `ARS` number - `AUD` number - `BRL` number - `CAD` number - `CHF` number - `CLP` number - `CNY` number - `COP` number - `CZK` number - `DKK` number - `EUR` number - `GBP` number - `HKD` number - `HUF` number - `IDR` number - `INR` number - `JPY` number - `KRW` number - `MXN` number - `MYR` number - `NOK` number - `NZD` number - `PEN` number - `PHP` number - `PLN` number - `RUB` number - `SAR` number - `SEK` number - `SGD` number - `THB` number - `TRY` number - `TWD` number - `USD` number - `VND` number - `ZAR` number - `percentDiscount` integer — A percentage amount deducted per unit within this tier. - `discountDuration` integer — The total number of consecutive billing periods this discount persists (only applicable to subscription plans; does not apply to one-time products). - `setupFee` PriceMap — A map of fixed prices across supported currencies. - `AED` number - `ARS` number - `AUD` number - `BRL` number - `CAD` number - `CHF` number - `CLP` number - `CNY` number - `COP` number - `CZK` number - `DKK` number - `EUR` number - `GBP` number - `HKD` number - `HUF` number - `IDR` number - `INR` number - `JPY` number - `KRW` number - `MXN` number - `MYR` number - `NOK` number - `NZD` number - `PEN` number - `PHP` number - `PLN` number - `RUB` number - `SAR` number - `SEK` number - `SGD` number - `THB` number - `TRY` number - `TWD` number - `USD` number - `VND` number - `ZAR` number - `edsFee` PriceMap — A map of fixed prices across supported currencies. - `AED` number - `ARS` number - `AUD` number - `BRL` number - `CAD` number - `CHF` number - `CLP` number - `CNY` number - `COP` number - `CZK` number - `DKK` number - `EUR` number - `GBP` number - `HKD` number - `HUF` number - `IDR` number - `INR` number - `JPY` number - `KRW` number - `MXN` number - `MYR` number - `NOK` number - `NZD` number - `PEN` number - `PHP` number - `PLN` number - `RUB` number - `SAR` number - `SEK` number - `SGD` number - `THB` number - `TRY` number - `TWD` number - `USD` number - `VND` number - `ZAR` number - `shippingFee` PriceMap — A map of fixed prices across supported currencies. - `AED` number - `ARS` number - `AUD` number - `BRL` number - `CAD` number - `CHF` number - `CLP` number - `CNY` number - `COP` number - `CZK` number - `DKK` number - `EUR` number - `GBP` number - `HKD` number - `HUF` number - `IDR` number - `INR` number - `JPY` number - `KRW` number - `MXN` number - `MYR` number - `NOK` number - `NZD` number - `PEN` number - `PHP` number - `PLN` number - `RUB` number - `SAR` number - `SEK` number - `SGD` number - `THB` number - `TRY` number - `TWD` number - `USD` number - `VND` number - `ZAR` number - `attributes` object — A key-value map of custom metadata tied specifically to this order item. Requires an authenticated request. - `subscriptionOverrides` SubscriptionAttribute — Defines configuration attributes specific to subscription products. Requires an authenticated request to modify. - `billingFrequency` Interval — Defines the frequency of a recurring billing cycle or scheduled notification. - `intervalUnit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR' | 'ON_DEMAND' — The unit of time defining a billing or reminder interval. Evaluated in conjunction with an interval length. - `intervalLength` integer — The number of units defining the interval. - `intervalCount` integer — The total number of consecutive intervals that make up this plan or sequence. - `trialDays` integer — The number of free trial days before the first billing cycle occurs. - `paymentMethodsOrder` PaymentMethodType[] — Dictates the explicit sorting order of payment methods presented to the buyer. Unsupported payment methods are automatically suppressed. Requires an authenticated request. - `hidePaymentMethods` PaymentMethodType[] — Explicitly filters the provided payment methods from the buyer's interface. Requires an authenticated request. ## Response `200` OK - CreateOrderSessionResponse — Response returned after creating an order session. - `id` string — Unique identifier for the order session. - `currency` string — 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. - `expires` integer — Expiration timestamp for the order session in milliseconds since the Unix epoch. After this timestamp, the order session is no longer valid. - `order` string, nullable — Identifier for the created order. If no order has been created yet, this field is null. - `account` string — Unique identifier for the account associated with the order session. - `subtotal` number, float — Subtotal amount for the order session. - `items` object[] — Items included in the order session. - `product` string — Product path of the product included in the order. - `quantity` integer — Number of units of the product being ordered. --- [API](https://skmtc.dev/fastspring/apis/fastspring-api-accounts.md) · [All operations](https://skmtc.dev/fastspring/apis/fastspring-api-accounts/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fastspring/fastspring-api-accounts/revisions/ae2f0b97db3e/schema)