--- title: "Add session item" method: POST path: "/v2/checkouts/{checkoutPath}/sessions/{sessionId}/cart/items" tags: ["Session"] --- # Add session item `POST /v2/checkouts/{checkoutPath}/sessions/{sessionId}/cart/items` Appends a new product item to the cart of an existing order session. ## 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 - OrderItemRequest — Details a specific line item being added or modified within a 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. ## Response `200` Successfully added the item to the session. - OrderItemResponse — Details the state and calculated pricing for a specific line item within the active cart. - `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. ## Other responses - `400` — Bad request. Indicates invalid input properties. --- [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)