--- title: "Update session" method: PUT path: "/v2/checkouts/{checkoutPath}/sessions/{sessionId}" tags: ["Session"] --- # Update session `PUT /v2/checkouts/{checkoutPath}/sessions/{sessionId}` Updates an existing order session. Overwrites customer details, items, and custom prices with the provided arrays. Requires an authenticated request to modify restricted fields. ## Path parameters - `checkoutPath` string, 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. - `sessionId` string, required — The unique identifier of the order session. ## 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` Successfully updated the session. - SessionResponse — Defines the core architecture and calculated state of a returned order session. - `id` string — The unique primary identifier representing the established session. - `created` string, date-time — The ISO 8601 timestamp marking the exact moment the session was initialized. - `expires` string, 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. - `locale` string — The display language code currently applied to the session formatting. - `country` string — The 2-letter ISO country code denoting the buyer's billing location utilized for localized pricing. - `currency` string — The active currency code utilized for all pricing calculations. - `live` boolean — Indicates `true` if the session is currently transacting real funds against live merchant accounts. - `customer` CustomerResponse — Consolidates the established customer and billing data associated with the session. - `accountId` string — The unique identifier mapping the buyer to a FastSpring account record. Revealed only on authenticated requests. - `externalAccountId` string — The external ID mapping the buyer to a seller's internal platform. Revealed only on authenticated requests. - `savedPaymentMethod` object — The details of a previously vaulted payment method associated with the buyer's account. - `paymentMethodType` string — Identifies the specific payment method brand or channel. - `display` string — A masked identifier safely describing the vaulted payment method, generally exposing only the last 4 digits. - `billToContact` BillToContactResponse — The billing contact details used to process the payment, calculate localized taxes, and generate the invoice. - `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` BillToAddressResponse — 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` ShipToContactResponse — 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` ShipToAddressResponse — 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. - `accountTags` object — A key-value map of custom tags applied to the buyer's account. - `taxId` string — The buyer's active VAT, GST, or CPF identification number. - `taxIdRegion` string — The 2-letter state or province code associated with a US tax exemption. - `orderTags` object — A key-value map of custom metadata configured to attach to the finalized order record. - `cart` CartResponse — Details the active state of the cart, providing a list of line items and the finalized calculated totals for the entire session. - `couponCode` string — The specific promotional coupon code evaluated by the session. - `couponHasApplied` boolean — Indicates `true` if the submitted `couponCode` successfully validated against the cart's line items and triggered a discount. - `lineItems` OrderItemResponse[] — The list of calculated product items currently residing in the session. - `productPath` string — The unique identifier of the selected product. - `quantity` integer — The total volume of units configured for purchase. - `quantityBehavior` string — Indicates whether the buyer is allowed to modify the item quantity during checkout. - `quantityDefault` integer — The original default quantity associated with the item before any modifications. - `virtualProduct` boolean — Indicates `true` if the item was dynamically constructed in the request and does not map to a saved catalog product. - `price` object — Contains all calculated price elements for the line item including discounts, totals, and localized formatting. - `unitNetPrice` number — The base price calculated for exactly 1 unit, factoring in applied discounts. Includes taxes if `taxIncluded` dictates inclusive pricing. - `unitNetPriceDisplay` string — The `unitNetPrice` mapped to a localized currency string. - `unitListPrice` number — The base price calculated for exactly 1 unit, ignoring any applied discounts. Includes taxes if `taxIncluded` dictates inclusive pricing. - `unitListPriceDisplay` string — The `unitListPrice` mapped to a localized currency string. - `unitDiscount` number — The absolute discount value deducted from 1 unit. - `unitDiscountDisplay` string — The `unitDiscount` mapped to a localized currency string. - `extendedTotalDiscount` number — The absolute total discount value calculated across all units (`unitDiscount` * `quantity`). - `extendedTotalDiscountDisplay` string — The `extendedTotalDiscount` mapped to a localized currency string. - `extendedNetTotal` number — The final, grand total calculated for all units, factoring in applied discounts. Includes taxes if `taxIncluded` dictates inclusive pricing. - `extendedNetTotalDisplay` string — The `extendedNetTotal` mapped to a localized currency string. - `extendedListTotal` number — The subtotal calculated for all units, ignoring applied discounts. Includes taxes if `taxIncluded` dictates inclusive pricing. - `extendedListTotalDisplay` string — The `extendedListTotal` mapped to a localized currency string. - `taxIncluded` 'TAXES_INCLUDED_IN_PRICE' | 'TAXES_ADDED_TO_PRICE' — Indicates the tax calculation mode applied to the returned price fields. - `unitTaxAmount` number — The absolute tax amount calculated for exactly 1 unit. - `unitTaxAmountDisplay` string — The `unitTaxAmount` mapped to a localized currency string. - `extendedTaxTotal` number — The absolute total tax amount calculated across all units (`unitTaxAmount` * `quantity`). - `extendedTaxTotalDisplay` string — The `extendedTaxTotal` mapped to a localized currency string. - `taxPercent` number — The effective tax rate percentage calculated for the item based on the buyer's location and tax status. - `taxExempt` boolean — Indicates `true` if the buyer qualifies for zero-rated taxes based on an evaluated `taxId`. - `productDiscountDuration` integer — The total number of consecutive billing periods a product-level discount will be applied. - `couponDiscountDuration` integer — The total number of consecutive billing periods a coupon-level discount will be applied. - `productType` 'ONE_TIME' | 'SUBSCRIPTION_PLAN' — Categorizes the product as either a one-time purchase or a recurring charge. - `removable` boolean — Indicates `true` if the interface should allow the buyer to remove the item from the cart. - `bundle` boolean — Indicates `true` if the item serves as a parent bundle containing sub-products. - `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. - `productFormat` 'DIGITAL' | 'PHYSICAL' — Categorizes the fulfillment logic format of the product. - `attributes` object — A key-value map of custom metadata associated with the line item. - `subscription` 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. - `netTotal` number — The grand total calculated for the cart, factoring in all applied discounts. Includes or excludes taxes based on the value of `taxIncluded`. - `netTotalDisplay` string — The `netTotal` mapped to a localized currency string. - `listTotal` number — The subtotal calculated for the cart, ignoring applied discounts. Includes or excludes taxes based on the value of `taxIncluded`. - `listTotalDisplay` string — The `listTotal` mapped to a localized currency string. - `withTaxNetTotal` number — A forced-calculation total factoring in both applied discounts and evaluated taxes, regardless of the `taxIncluded` setting. - `withTaxNetTotalDisplay` string — The `withTaxNetTotal` mapped to a localized currency string. - `withTaxListTotal` number — A forced-calculation subtotal ignoring applied discounts but factoring in evaluated taxes, regardless of the `taxIncluded` setting. - `withTaxListTotalDisplay` string — The `withTaxListTotal` mapped to a localized currency string. - `withoutTaxNetTotal` number — A forced-calculation total factoring in applied discounts but stripping out all evaluated taxes, regardless of the `taxIncluded` setting. - `withoutTaxNetTotalDisplay` string — The `withoutTaxNetTotal` mapped to a localized currency string. - `withoutTaxListTotal` number — A forced-calculation subtotal ignoring applied discounts and stripping out all evaluated taxes, regardless of the `taxIncluded` setting. - `withoutTaxListTotalDisplay` string — The `withoutTaxListTotal` mapped to a localized currency string. - `discountTotal` number — The absolute sum of all discounts (both product and coupon) deducted from the cart. - `discountTotalDisplay` string — The `discountTotal` mapped to a localized currency string. - `couponDiscountTotal` number — The specific absolute sum discounted explicitly by an evaluated coupon. - `couponDiscountTotalDisplay` string — The `couponDiscountTotal` mapped to a localized currency string. - `productDiscountTotal` number — The specific absolute sum discounted explicitly by configured volume or catalog product discounts. - `productDiscountTotalDisplay` string — The `productDiscountTotal` mapped to a localized currency string. - `taxIncluded` 'TAXES_INCLUDED_IN_PRICE' | 'TAXES_ADDED_TO_PRICE' — Indicates the tax calculation mode applied to the returned core price fields. - `taxTotal` number — The absolute sum of all taxes calculated across the cart. - `taxTotalDisplay` string — The `taxTotal` mapped to a localized currency string. - `taxRate` number — The effective tax rate percentage calculated across the cart based on the buyer's location. - `paymentMethods` PaymentMethod[] — A structured, ordered list specifying the active payment methods the session makes available to the buyer. - `id` 'ACH' | 'ALIPAY' | 'AMAZON' | 'APPLE_PAY' | 'CARD' | 'GOOGLE_PAY' | 'IDEAL' | 'KAKAOPAY' | 'KLARNA' | 'MERCADO_PAGO' | 'PAYPAL' | 'PIX' | 'SEPA' | 'TOSSPAY' | 'UPI' | 'WECHAT_PAY' | 'WIRE' | 'QUOTE' | 'PURCHASE_ORDER' | 'UNKNOWN' — Identifies the specific payment method brand or channel. - `description` string — The internal system key or localization reference used to map the payment method to its translated display name in the frontend interface. - `requiredFieldElements` string[] — A list of specific buyer data points associated with a checkout interface form. - `showFieldElements` string[] — A list of specific buyer data points associated with a checkout interface form. - `supportedProductTypes` string[] — A list defining whether the payment method supports one-time purchases, subscription plans, or both. - `variants` string[] — A list of explicitly supported card brands or sub-channels handled by this payment method. - `hidePaymentMethods` string[] — A list identifying specific payment methods explicitly filtered or hidden from the interface. - `checkoutUrls` object — A collection mapping distinct frontend URL flows required to render the session. - `webcheckoutUrl` string — The absolute URL designed to immediately redirect the buyer to a hosted Web checkout. - `warnings` Warning[] — A list detailing any non-fatal errors or ignored input values encountered while actively processing the session. - `code` 'INVALID_PROMO_CODE' | 'INVALID_COUNTRY' | 'CHECKOUT_NOT_LIVE' | 'INVALID_TAX_ID' | 'INVALID_BUYER_IP' | 'INVALID_LOCALE' | 'INVALID_POSTAL_CODE' — A constant code mapping to the specific type of warning triggered. Used to drive conditional messaging in the frontend. - `field` string — The name of the specific input parameter or field that triggered the warning. - `message` string — A human-readable description detailing the cause of the warning. - `checkoutStatus` string[] — 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. ## Other responses - `400` — Bad request. Indicates invalid input properties or values. --- [API](https://skmtc.net/fastspring/apis/fastspring-api-accounts.md) · [All operations](https://skmtc.net/fastspring/apis/fastspring-api-accounts/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fastspring/fastspring-api-accounts/versions/ae2f0b97db3e/schema)