--- title: "Apply coupon" method: POST path: "/orchestrator/carts/{cartId}/coupons/{couponCode}" tags: ["Carts"] --- # Apply coupon `POST /orchestrator/carts/{cartId}/coupons/{couponCode}` ## Request - Base URL: `https://api.fabric.inc/v3` - URL: `https://api.fabric.inc/v3/orchestrator/carts/{cartId}/coupons/{couponCode}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Apply a coupon code to the corresponding cart. The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter. The coupon code generated when [creating a custom coupon](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) in Copilot is used in the path parameter. ## Path parameters - `cartId` string, required - `couponCode` string, required ## Headers - `x-fabric-tenant-id` string, required - `x-fabric-request-id` string - `x-fabric-channel-id` string, required ## Response `200` Applies coupon to the cart - CartResponse - `id` string: The unique identifier of the cart that was passed in the parameter. - `attributes` Attributes: Custom attributes used to describe the cart, such as a wishlist cart. - `configuration` CartConfiguration: Cart [configurations](/v3/api-reference/carts-v3/configuration-behaviors) determine the behavior within the cart. - `order` OrderConfiguration: Configuration settings related to order validation and processing. - `validate` OrderValidateConfiguration: Order validate determines the blocking behavior when creating an order draft. - `paymentsRemaining` 'BLOCK' | 'NONE': The behavior that is executed based on the selected configuration. The default setting is BLOCK. - `taxRemaining` 'BLOCK' | 'NONE': The behavior that is executed based on the selected configuration. The default setting is BLOCK. - `invalidItem` 'BLOCK' | 'NONE': The behavior that is executed based on the selected configuration. The default setting is BLOCK. - `itemOutOfStock` 'BLOCK' | 'NONE': The behavior that is executed based on the selected configuration. The default setting is BLOCK. - `product` ProductConfiguration: Configuration settings related to product behavior and cache expiry. - `cacheExpiry` integer: Duration in seconds until product validation data expires. - `behaviors` ProductBehaviour: Behaviors related to inventory actions, such as adding the item or removing the item. - `add` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is REJECT. - `update` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `get` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `cacheExpiry` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `maxQuantity` MaxQtyConfiguration: Item max quantity configurations - `limit` integer: The maximum quantity of an individual line item that can be added to the cart. - `behaviors` MaxQtyBehaviour: Max quantity behaviors - `add` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is REJECT. - `update` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `get` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default setting is WARN. - `inventory` InventoryConfiguration: Configuration settings related to inventory management and checks. - `cacheExpiry` integer: Duration in seconds until inventory validation data expires. - `behaviors` InventoryBehaviour: Behaviors related to inventory actions, such as adding the item or removing the item. - `add` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is REJECT. - `update` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `get` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `cacheExpiry` 'WARN' | 'DROP' | 'REJECT' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `check` 'SKU' | 'LINE_ITEM': This setting is used to determine how you check inventory. The options are SKU or LINE_ITEM. - `tax` TaxConfiguration: Configuration settings for tax calculations and behaviors. - `cacheExpiry` integer: Duration in seconds until the tax data expires. - `behaviors` TaxBehaviour: Tax behaviors - `cacheExpiry` 'WARN' | 'NONE': The behavior that is executed based on the selected configuration. The default behavior is WARN. - `promotions` PromotionsConfiguration: Configuration settings related to promotions and their cache expiry. - `cacheExpiry` integer - `behaviors` Behavior: Configuration for different behaviors in the system - `add` 'BLOCK' | 'REJECT' | 'WARN' | 'NONE': Configuration values that define [behavior actions](/v3/api-reference/carts-v3/configuration-behaviors). - `update` 'BLOCK' | 'REJECT' | 'WARN' | 'NONE': Configuration values that define [behavior actions](/v3/api-reference/carts-v3/configuration-behaviors). - `get` 'BLOCK' | 'REJECT' | 'WARN' | 'NONE': Configuration values that define [behavior actions](/v3/api-reference/carts-v3/configuration-behaviors). - `cacheExpiry` 'BLOCK' | 'REJECT' | 'WARN' | 'NONE': Configuration values that define [behavior actions](/v3/api-reference/carts-v3/configuration-behaviors). - `customerContext` CustomerContext: Customer context object containing customer information. - `id` string: The Customer ID that was added to the customer attribute when using the [Update customer](/v3/api-reference/carts-v3/customer/update-customer) endpoint. - `segments` SegmentObject[]: An array containing segments of customer information. - `name` string: Segment name - `value` string[]: Segment values - `attributes` object: Customer attributes such as email. - `sessionId` string: Session ID of the customer. - `status` 'ACTIVE' | 'SOFT_DELETE': The cart status indicates whether the cart is active or deleted. - `state` State[]: The resource state is stored in an array that holds information about the current status of the cart. - `resource` 'ITEM' | 'CART' | 'FULFILLMENT' | 'PAYMENT' | 'FEE' | 'VALIDATION': The type of resource indicating its current state, such as a cart. - `resourceId` string: The ID used to reference the resource's state, such as a cart. - `key` string: The key used to map the state of the resource. - `description` string: A detailed description of the resource's current state, such as the absence of payment details. - `price` PriceDetail: The sum of the total amount of the cart. - `total` number, float: The grand total, inclusive of all charges and discounts. - `subtotal` number, float: The subtotal of all items. - `tax` number, float: The total tax calculated amount. - `fulfillments` number, float: The total fulfillments amount. - `discounts` number, float: The total discounts amount. - `fees` number, float: The total fees amount. - `adjustments` number, float: The total adjustments amount. - `promotions` Promotions: A collection of promotions applied to the cart. - `total` number, float: The total value of all applied promotions. - `collection` Promotion[]: An array containing promotions in the collection. - `id` string: The unique identifier of the promotion. - `title` string: Promotion title - `type` string: The type of promotion, such as percentage or fixed value. - `value` number, float: The value of the promotion, indicating the amount of the discount applied. This can be a fixed amount or a percentage. - `attributes` object: Custom attributes provide more context for the promotion. - `fees` Fee: A collection of fees associated with the cart. - `id` string: The unique identifier of the fee associated with the cart that was generated when making [Create fee](/v3/api-reference/carts-v3/fees/create-fees) endpoint. - `name` string: Name of the fee - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `taxable` boolean: A boolean value that determines whether a fee is taxable. - `attributes` object: Custom attributes that provide more context for the fee, such as the source of the fee. - `tax` TaxCollection: A collection of taxes. - `total` number: Tax total in the collection. - `collection` Tax[]: An array containing taxes in a collection. - `amount` number: Tax amount - `attributes` object: Custom attributes to provide more context to the tax, such as the rate and the type of tax. - `updatedAt` string: The date and time when the fee was last updated. - `createdAt` string: The date and time when the fee was created. - `taxDetails` FeeTaxDetails: Tax details used to determine tax for a cart fee. - `destinationAddress` string: The destination address where the item will be delivered. - `originAddress` string: The origin address from which the item will be fulfilled. - `adjustments` AdjustmentCollection: A collection of adjustments made to the cart. - `total` number: Adjustments total in a collection. - `collection` Adjustment[]: An array containing adjustments in the collection. - `id` string: The Adjustment ID generated when an adjustment was created using the [Create adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint. - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `reason` string: The reason for the adjustment. - `attributes` object: Custom attributes used for price adjustments. - `updatedAt` string: The date and time when the adjustment was last updated. - `createdAt` string: The date and time when the adjustment was created. - `addresses` object: A map of addresses added to the cart. - `a8577d7f0d4d4b228e857b4a2e90dc93` Address: Address - `id` string: The Address ID generated when an address was created using the [Create address](/v3/api-reference/carts-v3/addresses/create-addresses) endpoint. - `name` Name - `first` string: First name - `last` string: Last name - `email` string: Email - `phone` Phone - `number` string: Phone number - `type` string: Type of phone number (e.g., MOBILE, HOME) - `addressLine1` string: Address line 1 - `addressLine2` string: Address line 2 - `addressLine3` string: Address line 3 - `addressLine4` string: Address line 4 - `city` string: City - `region` string: State, Province or Area - `country` string: Country - `postalCode` string: Postal code or zip code - `updatedAt` string: The date and time the address was last updated. - `createdAt` string: The date and time the address was created. - `lineItems` ItemCollection: A collection of items in the cart. - `total` number: Item total in a collection. - `collection` ItemResponseDto[]: An array containing items in the collection. - `id` string: The unique identifier of the item. - `sku` string: The Stock Keeping Unit (SKU) associated with the item, used for inventory tracking and management. - `refId` string: An alternative identifier associated with the item, used for additional tracking or referencing. - `quantity` integer: An integer that displays the total quantity of the item. - `priceListId` string: The unique identifier for a price list, used to reference and manage pricing information. - `position` integer: Position of item in a cart. - `price` ItemPrice: Item price - `unit` number: The unit price of the item. - `amount` number: The total price of the item, inclusive of quantity. - `fees` FeesCollection: A collection of fees associated with the cart. - `total` number: The total fees amount in the collection. - `collection` Fee[]: An array containing all fees and their details in a collection. - `id` string: The unique identifier of the fee associated with the cart that was generated when making [Create fee](/v3/api-reference/carts-v3/fees/create-fees) endpoint. - `name` string: Name of the fee - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `taxable` boolean: A boolean value that determines whether a fee is taxable. - `attributes` object: Custom attributes that provide more context for the fee, such as the source of the fee. - `tax` TaxCollection: A collection of taxes. - `total` number: Tax total in the collection. - `collection` Tax[]: An array containing taxes in a collection. - … - `updatedAt` string: The date and time when the fee was last updated. - `createdAt` string: The date and time when the fee was created. - `taxDetails` FeeTaxDetails: Tax details used to determine tax for a cart fee. - `destinationAddress` string: The destination address where the item will be delivered. - `originAddress` string: The origin address from which the item will be fulfilled. - `promotions` ItemPromotionsCollection: Collection of item promotions. - `total` number: Discount total in the collection. - `collection` ItemPromotion[]: An array containing promotions in the collection. - `id` string: The unique identifier of the promotion. - `amount` number: The discount amount applied to the item, excluding quantity. - `quantity` integer: The An integer that displays the total quantity of the item. for which the discount is applicable. - `proration` ProrationSpread: Prorations - `spread` Proration[]: An array containing details about adjustments made to charges based on partial usage. Each entry in the array represents a specific proration adjustment, including the amount. - … - `adjustments` AdjustmentCollection: A collection of adjustments made to the cart. - `total` number: Adjustments total in a collection. - `collection` Adjustment[]: An array containing adjustments in the collection. - `id` string: The Adjustment ID generated when an adjustment was created using the [Create adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint. - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `reason` string: The reason for the adjustment. - `attributes` object: Custom attributes used for price adjustments. - `updatedAt` string: The date and time when the adjustment was last updated. - `createdAt` string: The date and time when the adjustment was created. - `fulfillment` ItemFulfillment: Item Fulfillment - `id` string: The identifier of the fulfillment linked to the item. - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `inventory` Inventory - `channels` object - `type` string: Channel type (e.g., WEB_PICKUP, WEB_SHIP) - `locationNumber` string: Location number - `channelId` string: x-fabric-channel-id identifies the sales channel where the API request is being made; primarily for multichannel use cases. The channel ids are 12 corresponding to US and 13 corresponding to Canada. The default channel id is 12. This field is required. - `networkCode` string: Network code (for shipping channels) - `type` string: Inventory type (e.g., availableToPurchase, availablePreorder) - `tax` TaxCollection: A collection of taxes. - `total` number: Tax total in the collection. - `collection` Tax[]: An array containing taxes in a collection. - `amount` number: Tax amount - `attributes` object: Custom attributes to provide more context to the tax, such as the rate and the type of tax. - `attributes` object: Custom attributes to provide more context for the item. - `tax` TaxCollection: A collection of taxes. - `total` number: Tax total in the collection. - `collection` Tax[]: An array containing taxes in a collection. - `amount` number: Tax amount - `attributes` object: Custom attributes to provide more context to the tax, such as the rate and the type of tax. - `taxCode` string: The code used to identify and apply tax rates for transactions. - `updatedAt` string: The date and time in UTC when the cart was last updated. - `createdAt` string: The date and time in UTC when the cart was last updated. - `summary` Summary: A summary of items in the cart. - `totalItems` integer: The total number of items in the cart, inclusive of quantity. - `totalUniqueItems` integer: The total number of unique items in the cart. - `fulfillments` object: A map of fulfillments added to the cart. - `d6229cdb0c5b4885b1b213b94d02488e` Fulfillment: A fulfillment object containing important fulfillment information. - `id` string: The Fulfillment ID generated when a fulfillment was created using the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint. - `type` 'SHIP_TO' | 'BOPIS' | 'ROPIS': Determines the type of fulfillment. - `refId` string: An alternative identifier for fulfillments, used for additional tracking or referencing. - `attributes` object: Custom attributes to provide more context to the fulfillment, such as where it was made. - `originAddress` string: The identifier of the address where the item is being fulfilled. - `destinationAddress` string: The identifier of the address where the item is being shipped. - `locationId` string: Unique identifier of the store. - `pickupPerson` PickupPerson: Pickup person details - `primary` Person: Name of the pickup person. - `name` Name, required - `first` string: First name - `last` string: Last name - `email` string: Email of the pickup person. - `phone` Phone - `number` string: Phone number - `type` string: Type of phone number (e.g., MOBILE, HOME) - `secondary` Person[]: An array containing secondary people for pickup. - `name` Name, required - `first` string: First name - `last` string: Last name - `email` string: Email of the pickup person. - `phone` Phone - `number` string: Phone number - `type` string: Type of phone number (e.g., MOBILE, HOME) - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `promotions` FulfillmentPromotionCollection: A collection of promotions applied to the fulfillment. - `total` number: The total discount applied within a collection. - `collection` FulfillmentPromotion[]: An array containing the promotions within a collection. - `id` string: Identifier of a promotion - `amount` number: The discount amount applied to a fulfillment. - `fees` FeesCollection: A collection of fees associated with the cart. - `total` number: The total fees amount in the collection. - `collection` Fee[]: An array containing all fees and their details in a collection. - `id` string: The unique identifier of the fee associated with the cart that was generated when making [Create fee](/v3/api-reference/carts-v3/fees/create-fees) endpoint. - `name` string: Name of the fee - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `taxable` boolean: A boolean value that determines whether a fee is taxable. - `attributes` object: Custom attributes that provide more context for the fee, such as the source of the fee. - `tax` TaxCollection: A collection of taxes. - `total` number: Tax total in the collection. - `collection` Tax[]: An array containing taxes in a collection. - … - `updatedAt` string: The date and time when the fee was last updated. - `createdAt` string: The date and time when the fee was created. - `taxDetails` FeeTaxDetails: Tax details used to determine tax for a cart fee. - `destinationAddress` string: The destination address where the item will be delivered. - `originAddress` string: The origin address from which the item will be fulfilled. - `adjustments` AdjustmentCollection: A collection of adjustments made to the cart. - `total` number: Adjustments total in a collection. - `collection` Adjustment[]: An array containing adjustments in the collection. - `id` string: The Adjustment ID generated when an adjustment was created using the [Create adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint. - `price` ResourcePrice: Price details - `amount` number, required: Total resource amount - `reason` string: The reason for the adjustment. - `attributes` object: Custom attributes used for price adjustments. - `updatedAt` string: The date and time when the adjustment was last updated. - `createdAt` string: The date and time when the adjustment was created. - `tax` TaxCollection: A collection of taxes. - `total` number: Tax total in the collection. - `collection` Tax[]: An array containing taxes in a collection. - `amount` number: Tax amount - `attributes` object: Custom attributes to provide more context to the tax, such as the rate and the type of tax. - `coupons` Coupon[]: An array containing all coupons added to the cart. - `code` string: Coupon code - `updatedAt` string: The date when the coupon was added to the cart. - `appliedCoupons` Coupon[]: An array containing all coupons applied to the cart. - `code` string: Coupon code - `updatedAt` string: The date when the coupon was added to the cart. - `notAppliedCoupons` Coupon[]: An array containing any coupons that were ineligible and not applied to the cart. - `code` string: Coupon code - `updatedAt` string: The date when the coupon was added to the cart. - `validations` ValidationData - `promotions` PromotionValidationData: An object that contains promotion validation data. - `updatedAt` string: The latest date when promotions data was added to the cart. - `appliedCoupons` string[]: An array containing coupons that have been added to the cart. - `refreshRequired` boolean: A boolean value that determines whether promotions require a refresh. - `lineItems` LineItemValidationData[] - `sku` string: The SKU of the item. - `inventory` InventoryValidationData: Inventory validation details - `channels` object: The inventory channels associated with the item. - `counters` object: The inventory counters available for the item. - `updatedAt` string: The latest date when inventory was added to the cart. - `product` PIMValidationData - `availableSkus` SKUValidationData[]: An array containing product validation data. - `sku` string: The SKU that exists within a Product Information Management (PIM) service. - `updatedAt` string: The latest date when product data was added to the cart. - `maxQuantity` integer: The maximum quantity allowed for a SKU. - `tax` TaxValidationData: Tax validation data - `updatedAt` string: Latest date the tax was added to the cart. - `payments` PaymentCollection: An object containing a collection of payments added to the cart. - `authorized` number: The payments that have been authorized within the collection. - `collection` Payment[]: An array containing payments within the collection. - `id` string: The Payment ID that was generated when a payment was created using the [Create payment](/v3/api-reference/carts-v3/payments/create-payments) endpoint. - `provider` string: The payment provider, such as Verifone, that offers functions like transaction processing, gateway management, and other financial services. - `processor` string: The payment processor, such as Stripe, responsible for handling and processing payment transactions by facilitating communication between the merchant and the issuing bank. - `method` string: Payment method, such as Apple Pay, used for processing transactions. - `methodType` string: Payment method type, such as a credit card. - `state` 'PENDING' | 'AUTHORIZED' | 'CAPTURED' | 'FAILED': Payment state indicates whether the payment has been successfully processed. - `authorization` PaymentAuthorization: Payment authorization - `amount` number, required: The amount for which the payment has been authorized. - `expiry` string: The date when the payment authorization expires. - `verifier` Verifier: Payment verifier - `type` string: The type of verification used, such as a token. - `key` string: The key used for payment verification. - `billToAddress` string: The Address ID that was generated when an address was created using the [Create address](/v3/api-reference/carts-v3/addresses/create-addresses) endpoint. - `cardDetails` object: Information about the card used for payment, such as gift card details. - `attributes` object: Custom attributes associated with the transaction, such as the name of the gift card used. - `channelId` string: Channel ID - `currency` string: The currency that the cart will use when an order is created. - `updatedAt` string: The date and time in UTC when the cart was last updated. - `createdAt` string: The date and time when a cart was created. - `suggestedProducts` SuggestedProduct[] - `id` string: The unique identifier for the suggested product. - `name` string: The name of the suggested product. - `description` string: The name of the suggested product. - `price` number, float: The price of the suggested product. - `promotionMessages` PromotionMessage[] - `message` string: The promotional message. - `code` string: The promotional code. - `errors` Error[] - `code` string: The error code as a result of the error. - `message` string: The error message to provide more context for the error. ## Other responses - `400`: Bad request - `401`: Unauthorized - `422`: Unprocessable Orchestration Error --- [API](https://skmtc.dev/fabric/apis/cart-orchestrator-api.md) - [All operations](https://skmtc.dev/fabric/apis/cart-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fabric/apis/cart-orchestrator-api/revisions/7c220dc4b452?raw)