openapi: 3.0.1
info:
title: Cart Actions Endpoints Items API
description: fabric's **Cart API** lets you add, update, and remove items from your Storefront cart, either as a guest user or as a logged-in user. It also provides functionality to merge carts when you switch from guest user to logged-in user, and apply coupons and other attributes (for example, gift wrapping) to the line items. Additionally, the API supports more advanced tasks such as using multiple carts within a B2B organization, sharing carts, and supporting a unified cart experience for multi-region and multi-brand businesses.<p>The Cart API provides high performance, scalability, multi-tenancy, and configurability to the end-to-end order processing actions that start from the item being added to the cart; through the pre-checkout stage that includes billing, shipping, and payment details; to the checkout stage where the order is processed and confirmed by fabric's Order Management System (OMS)
contact:
name: Cart Support
email: support.cnc@fabric.inc
license:
name: fabric API License
url: https://fabric.inc/api-license
version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
security:
- bearerAuth: []
tags:
- name: Items
description: Item endpoints are used to add, update and remove items from the Cart.
paths:
/carts/{cartId}/items:
post:
tags:
- Items
summary: Create Item
description: 'Creates the item in the cart.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
'
operationId: createItem
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateItemRequest'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Item not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
/carts/{cartId}/items/{itemId}:
get:
tags:
- Items
summary: Get Item
description: 'Returns the item from the cart.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/cart-and-checkout/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
'
operationId: getItem
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: itemId
in: path
required: true
schema:
type: string
description: The Item ID generated when the item was created using the [Create item](/v3/cart-and-checkout/api-reference/carts-v3/items/items) endpoint. You can find the ID in the line item collections.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ItemResponseDto'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Item not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
delete:
tags:
- Items
summary: Delete Item
description: 'Deletes the item from the cart.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/cart-and-checkout/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
'
operationId: deleteItem
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: itemId
in: path
required: true
schema:
type: string
description: The Item ID generated when the item was created using the [Create item](/v3/cart-and-checkout/api-reference/carts-v3/items/items) endpoint. You can find the ID in the line item collections.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
responses:
'204':
description: No Content
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Item not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
patch:
tags:
- Items
summary: Update Item
description: 'Updates the item in the cart.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The Item ID from the [Create item](/v3/cart-and-checkout/api-reference/carts-v3/items/items) endpoint is used in the path parameter.
'
operationId: updateItem
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: itemId
in: path
required: true
schema:
type: string
description: The Item ID generated when the item was created using the [Create item](/v3/cart-and-checkout/api-reference/carts-v3/items/items) endpoint. You can find the ID in the line item collections.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateItemRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CartResponse'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Item not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
components:
schemas:
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 corresponding cart.
example: 2024-06-13 16:50:00.682000+00:00
description: Coupon
State:
type: object
properties:
resource:
type: string
description: The type of resource indicating its current state, such as a cart.
example: CART
enum:
- ITEM
- CART
- FULFILLMENT
- PAYMENT
- FEE
- VALIDATION
resourceId:
type: string
description: The ID used to reference the resource's state, such as a cart.
example: c86f777b-1885-4ddf-961d-542ba80a69b8
key:
type: string
description: The key used to map the state of the resource.
example: MISSING_PAYMENT_DETAILS
description:
type: string
description: A detailed description of the resource's current state, such as the absence of payment details.
example: No payment details have been added to this Cart
description: Cart State
Address:
type: object
properties:
id:
type: string
description: The Address ID generated when an address was created using the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint.
example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
name:
$ref: '#/components/schemas/Name'
email:
type: string
description: Email
example: john@test.com
phone:
$ref: '#/components/schemas/Phone'
addressLine1:
type: string
description: Address line 1
example: 123 Park Road
addressLine2:
type: string
description: Address line 2
addressLine3:
type: string
description: Address line 3
addressLine4:
type: string
description: Address line 4
city:
type: string
description: City
example: Santa Cruz
region:
type: string
description: State, Province or Area
example: California
country:
type: string
description: Country
example: USA
postalCode:
type: string
description: Postal code or zip code
example: '12345'
updatedAt:
type: string
description: The date and time the address was last updated.
example: 2024-06-13 16:50:00.682000+00:00
createdAt:
type: string
description: The date and time the address was created.
example: 2024-06-13 16:50:00.682000+00:00
description: Address
ClientError:
type: object
properties:
type:
type: string
description: Error code, meant for machine consumption
example: BAD_REQUEST
message:
type: string
description: Human-readable error description
example: x-fabric-tenant-id is required
description: Client error details
TaxCollection:
type: object
properties:
total:
type: number
description: Tax total in the collection.
example: 3
collection:
type: array
description: An array containing taxes in a collection.
items:
$ref: '#/components/schemas/Tax'
description: A collection of taxes.
AdjustmentCollection:
type: object
properties:
total:
type: number
description: Adjustments total in a collection.
example: 2
collection:
type: array
description: An array containing adjustments in the collection.
items:
$ref: '#/components/schemas/Adjustment'
description: A collection of adjustments made to the corresponding cart.
Person:
required:
- name
type: object
properties:
name:
$ref: '#/components/schemas/Name'
email:
type: string
description: Email of the pickup person.
example: john@test.com
phone:
$ref: '#/components/schemas/Phone'
description: Name of the pickup person.
ItemPromotion:
type: object
properties:
id:
type: string
description: The unique identifier of the promotion.
example: bb44db95-6fbd-4eed-a1ed-4d99bc91250f
amount:
type: number
description: The discount amount applied to the item, excluding quantity.
example: 15
quantity:
type: integer
description: The quantity of the item for which the discount is applicable.
format: int32
example: 3
proration:
$ref: '#/components/schemas/ProrationSpread'
description: Item Promotion
OrderValidateConfiguration:
type: object
properties:
paymentsRemaining:
type: string
description: 'The behavior that is executed based on the selected configuration.
The default behavior is BLOCK.
'
enum:
- BLOCK
- NONE
taxRemaining:
type: string
description: 'The behavior that is executed based on the selected configuration.
The default behavior is BLOCK.
'
enum:
- BLOCK
- NONE
invalidItem:
type: string
description: 'The behavior that is executed based on the selected configuration.
The default behavior is BLOCK.
'
enum:
- BLOCK
- NONE
itemOutOfStock:
type: string
description: 'The behavior that is executed based on the selected configuration.
The default behavior is BLOCK.
'
enum:
- BLOCK
- NONE
description: Order validate determines the blocking behavior when creating an order draft.
ItemPrice:
type: object
properties:
unit:
type: number
description: The unit price of the item.
example: 10
amount:
type: number
description: The total price of the item, inclusive of quantity.
example: 100
description: Item price
ItemPromotionsCollection:
type: object
properties:
total:
type: number
description: Discount total in the collection.
example: 2
collection:
type: array
description: An array containing promotions in the collection.
items:
$ref: '#/components/schemas/ItemPromotion'
description: Collection of item promotions.
Price:
type: object
properties:
total:
type: number
description: The grand total, inclusive of all charges and discounts.
example: 800
subtotal:
type: number
description: The subtotal of all items amount.
example: 750
tax:
type: number
description: The tax total amount.
example: 20
fulfillments:
type: number
description: The fulfillments total amount.
example: 25
discounts:
type: number
description: The discounts total amount.
example: 10
fees:
type: number
description: The fees total amount.
example: 5
adjustments:
type: number
description: The adjustments total amount.
example: 10
description: The sum of the total amount of the cart.
ProductBehavior:
type: object
properties:
add:
type: string
description: 'The behavior that is executed based on the selected configuration.
The default setting 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.
OrderConfiguration:
type: object
properties:
validate:
$ref: '#/components/schemas/OrderValidateConfiguration'
description: Configuration settings related to order validation and processing.
SegmentObject:
type: object
properties:
name:
type: string
description: Segment name
example: membership
value:
type: array
description: Segment values
example:
- gold
- silver
items:
type: string
description: Segment values
example: '["gold","silver"]'
description: Segment
Payment:
type: object
properties:
id:
type: string
description: The Payment ID that was generated when a payment was created using the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint.
example: 6ef2067a-5d6b-4785-a090-96ea0078220d
provider:
type: string
description: The payment provider, such as Verifone, that offers functions like transaction processing, gateway management, and other financial services.
example: verifone
processor:
type: string
description: The payment processor, such as Stripe, responsible for handling and processing payment transactions by facilitating communication between the merchant and the issuing bank.
example: stripe
method:
type: string
description: Payment method, such as Apple Pay, used for processing transactions.
example: apple pay
methodType:
type: string
description: Payment method type, such as a credit card.
example: credit card
state:
type: string
description: Payment state indicates whether the payment has been successfully processed.
example: PENDING
enum:
- PENDING
- AUTHORIZED
- CAPTURED
- FAILED
authorization:
$ref: '#/components/schemas/PaymentAuthorization'
billToAddress:
type: string
description: The Address ID that was generated when an address was created using the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint.
example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
cardDetails:
type: object
description: Information about the card used for payment, such as gift card details.
additionalProperties:
type: object
description: Information about the card used for payment, such as gift card details.
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes associated with the transaction, such as the name of the gift card used.
example:
gift-card-name: custom name
description: Custom attributes associated with the transaction, such as the name of the gift card used.
example:
gift-card-name: custom name
description: Cart Payment
Name:
type: object
properties:
first:
type: string
description: First name
example: John
middle:
type: string
description: Middle name
example: S
last:
type: string
description: Last name
example: Doe
description: Name of the recipient of the order.
LineItemValidationData:
type: object
properties:
sku:
type: string
description: The SKU of the item.
example: SKU3
inventory:
$ref: '#/components/schemas/InventoryValidationData'
description: An object that contains item validation data.
Proration:
type: object
properties:
amount:
type: number
description: Proration amount for the item
example: 5
quantity:
type: integer
description: Proration quantity the amount is applicable for
format: int32
example: 3
description: Proration details of the item used for returns in an OMS system
FeeTaxDetails:
type: object
properties:
destinationAddress:
type: string
description: The destination address where the item will be delivered.
example: c86f777b-1885-4ddf-961d-542ba80a69b8
originAddress:
type: string
description: The origin address from which the item will be fulfilled.
example: c86f777b-1885-4ddf-961d-542ba80a69b8
description: Tax details used to determine tax for a cart fee.
ItemPriceRequest:
required:
- amount
- type
type: object
properties:
type:
type: string
description: 'Indicates whether the amount represents the **unit** price or the **line item** price of the item.
'
example: LINE_ITEM
enum:
- LINE_ITEM
- UNIT
amount:
minimum: 0
exclusiveMinimum: false
type: number
description: The price amount for either the unit or line item of the item.
example: 100
description: Item price request
ResourcePrice:
required:
- amount
type: object
properties:
amount:
minimum: 0
exclusiveMinimum: false
type: number
description: Total fees amount
example: 12.99
description: Price details
ProrationSpread:
type: object
properties:
spread:
type: array
description: 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.
items:
$ref: '#/components/schemas/Proration'
description: Prorations
ItemResponseDto:
type: object
properties:
id:
type: string
description: The unique identifier of the item that was linked from making [Create item](/v3/cart-and-checkout/api-reference/carts-v3/items/items) endpoint
example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
sku:
type: string
description: The Stock Keeping Unit (SKU) associated with the item, used for inventory tracking and management.
example: SKU3
refId:
type: string
description: An alternative identifier associated with the item, used for additional tracking or referencing.
example: '41'
quantity:
type: integer
description: Quantity of item
format: int32
example: 10
priceListId:
type: string
description: The unique identifier for a price list, used to reference and manage pricing information.
example: '10001'
position:
type: integer
description: Position of the item in the cart..
format: int32
example: 1
price:
$ref: '#/components/schemas/ItemPrice'
fees:
$ref: '#/components/schemas/FeesCollection'
promotions:
$ref: '#/components/schemas/ItemPromotionsCollection'
adjustments:
$ref: '#/components/schemas/AdjustmentCollection'
fulfillment:
$ref: '#/components/schemas/ItemFulfillment'
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes
example:
name: item-custom
description: Custom attributes
example:
name: item-custom
tax:
$ref: '#/components/schemas/TaxCollection'
taxCode:
type: string
description: The code used to identify and apply tax rates for transactions.
example: '10001'
updatedAt:
type: string
description: The date and time the Item was last updated
example: 2024-06-13 16:50:00.682000+00:00
createdAt:
type: string
description: The date and time a Item was created
example: 2024-06-13 16:50:00.682000+00:00
description: Item Response
MaxQtyConfiguration:
type: object
properties:
limit:
type: integer
description: Maximum quantity for an individual line item
format: int32
example: 100
behaviors:
$ref: '#/components/schemas/MaxQtyBehavior'
description: Item max quantity configurations
InventoryValidationData:
type: object
properties:
channels:
type: object
additionalProperties:
type: string
description: The inventory channels associated with the item.
example: '{"networkCode":"ShipToHome"}'
description: The inventory channels associated with the item.
example:
networkCode: ShipToHome
counters:
type: object
additionalProperties:
type: integer
description: The inventory counters available for the item.
format: int32
description: The inventory counters available for the item.
example:
backOrder: 15
preOrder: 100
updatedAt:
type: string
description: The latest date when inventory was added to the corresponding cart.
example: 2024-06-13 16:50:00.682000+00:00
description: Inventory validation details
FeesCollection:
type: object
properties:
total:
type: number
description: The total fees amount in the collection.
example: 5
collection:
type: array
description: An array containing all fees and their details in a collection.
items:
$ref: '#/components/schemas/Fee'
description: A collection of fees associated with the corresponding cart.
CartPromotionCollection:
type: object
properties:
total:
type: number
description: The total value of all applied promotions.
example: 32
collection:
type: array
description: An array containing promotions in the collection.
items:
$ref: '#/components/schemas/PromotionApplied'
description: A collection of promotions applied to the corresponding cart.
InventoryConfiguration:
type: object
properties:
cacheExpiry:
type: integer
description: Duration in seconds until inventory validation data expires.
format: int64
example: 7776000
behaviors:
$ref: '#/components/schemas/InventoryBehavior'
check:
type: string
description: This setting is used to determine how you check inventory. The options are SKU or LINE_ITEM.
example: SKU
enum:
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-items-api-openapi.yml