The Cart Orchestrator (ShopperXP) wraps Cart, Offers, Inventory, and Identity into a single storefront-facing surface. Storefront clients call one orchestrator endpoint per shopper action and the service fans out to the underlying commerce APIs in the correct sequence.
openapi: 3.0.1
info:
title: Cart Orchestrator API
description: API for managing shopping carts
version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
description: Production server
- url: https://stg.api.fabric.inc/v3
description: Staging server
security:
- bearerAuth: []
tags:
- name: Carts
description: >-
Cart endpoints are used to perform basic cart operations, such as create,
update, delete and more.
- name: LineItems
description: >-
LineItem endpoints are used to performbasic lineItem operations, such as
create, update, delete and more.
- name: CartPayments
description: >-
CartPayments endpoints are used to authorize or void payments that are
located within the shopping cart.
- name: OrderDrafts
description: >-
Order draft endpoints are used to create an order draft or get a generated
order draft.
paths:
/orchestrator/carts/{cartId}:
get:
summary: Get the Cart
description: >
Retrieves the cart information corresponding to the provided cart ID.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: getCart
tags:
- Carts
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
responses:
'200':
description: Get entire cart
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
delete:
summary: Delete Cart
description: >
Removes the cart corresponding to the provided cart ID.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: deleteCart
tags:
- Carts
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
responses:
'204':
description: Delete entire cart
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
/orchestrator/carts/{cartId}/coupons/{couponCode}:
post:
summary: Apply Coupon
description: >
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.
operationId: applyCoupon
tags:
- Carts
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
- name: couponCode
in: path
required: true
schema:
type: string
description: >-
The coupon code generated when [creating a custom
coupon](/v3/offers/user-guides/offers/coupons/overview) in Copilot.
responses:
'200':
description: Applies coupon to the cart
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
delete:
summary: Removes Coupon
description: >
Removes the coupon from the corresponding cart.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: removeCoupon
tags:
- Carts
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
- name: couponCode
in: path
required: true
schema:
type: string
description: >-
The coupon code generated when [creating a custom
coupon](/v3/offers/user-guides/offers/coupons/overview) in Copilot.
responses:
'200':
description: Coupon is removed from cart successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
/orchestrator/carts/{cartId}/items:
post:
summary: Add Items
description: >
Add items 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.
operationId: addItemsToCart
tags:
- LineItems
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddItemsToCartRequest'
responses:
'200':
description: Items added to the cart successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
patch:
summary: Update Items
description: >
Updates the item information in the corresponding cart.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: updateItems
tags:
- LineItems
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
requestBody:
description: Update line items
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateLineItemsRequest'
responses:
'200':
description: Items updated to the cart successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
delete:
summary: Delete Items
description: >
Removes the items from the corresponding cart.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: deleteItems
tags:
- LineItems
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
- name: itemId
in: query
required: true
schema:
type: string
description: Item ID of the item to remove.
responses:
'200':
description: Items deleted from the cart successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
/orchestrator/carts/{cartId}/items/{itemId}/actions/split:
post:
summary: Split Line Items
description: >
Splits the item associated with the corresponding cart into multiple
line items based on quantity.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
The Item ID from the [Create
item](/v3/api-reference/carts-v3/items/items) endpoint is used in the
path parameter.
operationId: splitLineItems
tags:
- LineItems
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
- name: itemId
in: path
required: true
schema:
type: string
description: >-
The unique identifier for the line item that is the target of the
split.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SplitLineItemsRequest'
required: true
responses:
'200':
description: Line items split successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
/orchestrator/carts/{cartId}/payments/actions/authorize:
post:
summary: Authorize Payments
description: >
Authorize payments made within the corresponding cart.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: authorizePayment
tags:
- CartPayments
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
responses:
'200':
description: Payments authorized successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
/orchestrator/carts/{cartId}/payments/actions/void:
post:
summary: Void Payments
description: >
Void payments made within the corresponding cart.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: voidPayment
tags:
- CartPayments
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
responses:
'200':
description: Payments void successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
/orchestrator/carts/{cartId}/order-drafts:
post:
summary: Create an Order Draft
description: >
Creates an order from the current cart.
The Cart ID from the [Create
cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the
path parameter.
operationId: createOrderDraft
tags:
- OrderDrafts
parameters:
- $ref: '#/components/parameters/XFabricTenantId'
- $ref: '#/components/parameters/XFabricRequestId'
- $ref: '#/components/parameters/XFabricChannelId'
- name: cartId
in: path
required: true
schema:
type: string
description: >-
The 24-character system-generated Cart ID. This ID is generated
using the [Create cart](/v3/api-reference/carts-v3/carts/carts)
endpoint.
requestBody:
description: Order draft request body
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderDraftRequest'
responses:
'200':
description: Order draft created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDraftResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
description: Unprocessable Orchestration Error
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableOrchestrationError'
components:
parameters:
XFabricTenantId:
name: x-fabric-tenant-id
in: header
required: true
schema:
type: string
description: >
A header used by fabric to identify the tenant making the request. You
must include tenant id in the authentication header for an API request
to access any of fabric’s endpoints. You can retrieve the tenant id ,
which is also called account id, from
[Copilot](/v3/platform/settings/account-details/getting-the-account-id).
This header is required.
XFabricRequestId:
name: x-fabric-request-id
in: header
required: false
schema:
type: string
description: Unique request ID for tracking.
XFabricChannelId:
name: x-fabric-channel-id
in: header
required: true
schema:
type: string
description: >-
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.
Authorization:
name: Authorization
in: header
required: true
schema:
type: string
description: >-
This is the authorization token used to authenticate the request. You
must pass the access token generated from the system app. For more
information, see the [Making your first API
request](/v3/api-reference/getting-started/getting-started-with-fabric-apis#procedure)
section.
responses:
BadRequest:
description: Bad request
Unauthorized:
description: Unauthorized
NotFound:
description: Cart not found
schemas:
AddItemsRequest:
type: object
properties:
cartId:
type: string
description: ID of the cart
example: 0e49199c-5849-4211-abe6-a97a3c4dcc56
items:
type: array
items:
$ref: '#/components/schemas/CartItem'
CartItem:
type: object
properties:
quantity:
type: integer
description: An integer that displays the total quantity of the item.
example: 3
itemId:
type: string
description: The unique identifier for an item.
example: '41'
sku:
type: string
description: >-
The Stock Keeping Unit (SKU) associated with the item, used for
inventory tracking and management.
example: SKU2
priceListId:
type: string
description: >-
The unique identifier for a price list, used to reference and manage
pricing information.
example: '100000'
price:
$ref: '#/components/schemas/PriceDetail'
fulfillment:
$ref: '#/components/schemas/Fulfillment'
CartResponse:
type: object
properties:
id:
type: string
description: The unique identifier of the cart that was passed in the parameter.
example: 0e49199c-5849-4211-abe6-a97a3c4dcc56
attributes:
$ref: '#/components/schemas/Attributes'
configuration:
$ref: '#/components/schemas/CartConfiguration'
customerContext:
$ref: '#/components/schemas/CustomerContext'
status:
type: string
description: The cart status indicates whether the cart is active or deleted.
example: ACTIVE
enum:
- ACTIVE
- SOFT_DELETE
state:
type: array
description: >-
The resource state is stored in an array that holds information
about the current status of the cart.
items:
$ref: '#/components/schemas/State'
price:
$ref: '#/components/schemas/PriceDetail'
promotions:
$ref: '#/components/schemas/Promotions'
fees:
$ref: '#/components/schemas/Fee'
adjustments:
$ref: '#/components/schemas/AdjustmentCollection'
addresses:
type: object
properties:
a8577d7f0d4d4b228e857b4a2e90dc93:
$ref: '#/components/schemas/Address'
description: A map of addresses added to the cart.
lineItems:
$ref: '#/components/schemas/ItemCollection'
summary:
$ref: '#/components/schemas/Summary'
fulfillments:
type: object
properties:
d6229cdb0c5b4885b1b213b94d02488e:
$ref: '#/components/schemas/Fulfillment'
description: A map of fulfillments added to the cart.
coupons:
type: array
description: An array containing all coupons added to the cart.
items:
$ref: '#/components/schemas/Coupon'
appliedCoupons:
type: array
description: An array containing all coupons applied to the cart.
items:
$ref: '#/components/schemas/Coupon'
notAppliedCoupons:
type: array
description: >-
An array containing any coupons that were ineligible and not applied
to the cart.
items:
$ref: '#/components/schemas/Coupon'
validations:
$ref: '#/components/schemas/ValidationData'
payments:
$ref: '#/components/schemas/PaymentCollection'
channelId:
type: string
description: Channel ID
example: '12'
currency:
type: string
description: The currency that the cart will use when an order is created.
example: USD
updatedAt:
type: string
description: The date and time in UTC when the cart was last updated.
example: 2024-06-13T16:50:00.682Z
createdAt:
type: string
description: The date and time when a cart was created.
example: 2024-06-13T16:50:00.682Z
suggestedProducts:
type: array
items:
$ref: '#/components/schemas/SuggestedProduct'
promotionMessages:
type: array
items:
$ref: '#/components/schemas/PromotionMessage'
errors:
type: array
items:
$ref: '#/components/schemas/Error'
Attributes:
type: object
description: Custom attributes used to describe the cart, such as a wishlist cart.
additionalProperties:
type: string
example:
attr1: attrValue
CartConfiguration:
type: object
properties:
order:
$ref: '#/components/schemas/OrderConfiguration'
product:
$ref: '#/components/schemas/ProductConfiguration'
inventory:
$ref: '#/components/schemas/InventoryConfiguration'
tax:
$ref: '#/components/schemas/TaxConfiguration'
promotions:
$ref: '#/components/schemas/PromotionsConfiguration'
description: >-
Cart
[configurations](/v3/api-reference/carts-v3/configuration-behaviors)
determine the behavior within the cart.
Coupon:
type: object
properties:
code:
type: string
description: Coupon code
example: VALID_COUPON
updatedAt:
type: string
description: The date when the coupon was added to the cart.
example: 2024-06-13T16:50:00.682Z
description: Coupon
OrderConfiguration:
type: object
properties:
validate:
$ref: '#/components/schemas/OrderValidateConfiguration'
description: Configuration settings related to order validation and processing.
OrderValidateConfiguration:
type: object
properties:
paymentsRemaining:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default setting is BLOCK.
enum:
- BLOCK
- NONE
taxRemaining:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default setting is BLOCK.
enum:
- BLOCK
- NONE
invalidItem:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default setting is BLOCK.
enum:
- BLOCK
- NONE
itemOutOfStock:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default setting is BLOCK.
enum:
- BLOCK
- NONE
description: >-
Order validate determines the blocking behavior when creating an order
draft.
ProductConfiguration:
type: object
properties:
cacheExpiry:
type: integer
description: Duration in seconds until product validation data expires.
format: int64
example: 7776000
behaviors:
$ref: '#/components/schemas/ProductBehaviour'
maxQuantity:
$ref: '#/components/schemas/MaxQtyConfiguration'
description: Configuration settings related to product behavior and cache expiry.
ProductBehaviour:
type: object
properties:
add:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is REJECT.
example: REJECT
enum:
- WARN
- DROP
- REJECT
- NONE
update:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is WARN.
example: WARN
enum:
- WARN
- DROP
- REJECT
- NONE
get:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is WARN.
example: WARN
enum:
- WARN
- DROP
- REJECT
- NONE
cacheExpiry:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is WARN.
example: WARN
enum:
- WARN
- DROP
- REJECT
- NONE
description: >-
Behaviors related to inventory actions, such as adding the item or
removing the item.
MaxQtyConfiguration:
type: object
properties:
limit:
type: integer
description: >-
The maximum quantity of an individual line item that can be added to
the cart.
format: int32
example: 100
behaviors:
$ref: '#/components/schemas/MaxQtyBehaviour'
description: Item max quantity configurations
MaxQtyBehaviour:
type: object
properties:
add:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is REJECT.
example: REJECT
enum:
- WARN
- DROP
- REJECT
- NONE
update:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is WARN.
example: WARN
enum:
- WARN
- DROP
- REJECT
- NONE
get:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default setting is WARN.
example: WARN
enum:
- WARN
- DROP
- REJECT
- NONE
description: Max quantity behaviors
InventoryConfiguration:
type: object
properties:
cacheExpiry:
type: integer
description: Duration in seconds until inventory validation data expires.
format: int64
example: 7776000
behaviors:
$ref: '#/components/schemas/InventoryBehaviour'
check:
type: string
description: >-
This setting is used to determine how you check inventory. The
options are SKU or LINE_ITEM.
example: SKU
enum:
- SKU
- LINE_ITEM
description: Configuration settings related to inventory management and checks.
InventoryBehaviour:
type: object
properties:
add:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is REJECT.
example: REJECT
enum:
- WARN
- DROP
- REJECT
- NONE
update:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is WARN.
example: WARN
enum:
- WARN
- DROP
- REJECT
- NONE
get:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is WARN.
example: WARN
enum:
- WARN
- DROP
- REJECT
- NONE
cacheExpiry:
type: string
description: |
The behavior that is executed based on the selected configuration.
The default behavior is WARN.
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-shopperxp-openapi.yml