openapi: 3.0.1
info:
title: Cart Actions Endpoints OrderDrafts 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: OrderDrafts
description: Order draft endpoints are used to create an order draft or get a generated order draft.
paths:
/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:
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 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/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
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 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 An integer that displays the total quantity of the item. for which the discount is applicable.
format: int32
example: 3
proration:
$ref: '#/components/schemas/ProrationSpread'
description: Item Promotion
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
OrderInfo:
type: object
properties:
id:
type: string
description: Identifier of an order draft to create an order.
example: 6d65755f-b1d9-4c9d-bb5b-118d317f8db4
number:
type: string
description: Order number
example: '100001'
lineItems:
type: array
description: An array containing items with associated custom data.
items:
$ref: '#/components/schemas/OrderDraftItemRequest'
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes, such as order status.
example:
orderStatus: ACTIVE
description: Custom attributes, such as order status.
example:
orderStatus: ACTIVE
description: Order information
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.
Payment:
type: object
properties:
id:
type: string
description: The Payment ID that was generated when a payment was created using the [Create payment](/v3/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/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
Promotions:
type: object
properties:
total:
type: number
format: float
description: The total value of all applied promotions.
example: 0
collection:
type: array
description: An array containing promotions in the collection.
items:
$ref: '#/components/schemas/Promotion'
description: A collection of promotions applied to the cart.
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"]'
Name:
type: object
properties:
first:
type: string
description: First name
example: John
last:
type: string
description: Last name
example: Doe
OrderDraftResponse:
type: object
properties:
order:
$ref: '#/components/schemas/OrderInfo'
cartId:
type: string
description: The unique identifier of the cart that was passed in the parameter.
example: 4ed2e918-fb5b-47ed-bca3-da514b6aa6bf
attributes:
$ref: '#/components/schemas/Attributes'
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'
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'
payments:
$ref: '#/components/schemas/PaymentCollection'
updatedAt:
type: string
format: date-time
description: The date and time in UTC when the cart was last updated.
example: '2024-06-24T16:57:47.112Z'
createdAt:
type: string
format: date-time
description: The date and time when a cart was created.
example: '2024-06-24T16:56:43.027Z'
errors:
type: array
items:
$ref: '#/components/schemas/Error'
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.
ResourcePrice:
required:
- amount
type: object
properties:
amount:
minimum: 0
exclusiveMinimum: false
type: number
description: Total resource amount
example: 12.99
description: Price details
CreateOrderDraftRequest:
type: object
properties:
orderSequence:
type: object
properties:
sequenceName:
description: Sequence configuration name
type: string
example: STORE_ORDER_NUMBER
sequenceKey:
description: Sequence identifier
type: string
example: SHOPZ
description: 'An order sequence is used to define a pattern or template for generating unique order numbers. This object contains the order sequence name and identifier.
'
orderNumber:
type: string
description: Order number based on the order sequence.
example: SHOPZ0000001
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.
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: An integer that displays the total quantity of the 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 item in a 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 to provide more context for the item.
example:
name: item-custom
description: Custom attributes to provide more context for the item.
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 in UTC when the cart was last updated.
example: 2024-06-13 16:50:00.682000+00:00
createdAt:
type: string
description: The date and time in UTC when the cart was last updated.
example: 2024-06-13 16:50:00.682000+00:00
description: Item Response
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 cart.
CustomerContext:
type: object
properties:
id:
type: string
description: The Customer ID that was added to the customer attribute when using the [Update customer](/v3/api-reference/carts-v3/customer/update-customer) endpoint.
example: '109840938'
segments:
type: array
description: An array containing segments of customer information.
items:
$ref: '#/components/schemas/SegmentObject'
attributes:
type: object
additionalProperties:
type: object
description: Customer attributes such as email.
example:
email: test@gmail.com
description: Customer attributes such as email.
example:
email: test@gmail.com
sessionId:
type: string
description: Session ID of the customer.
example: 3a5fd2d3-5c96-4e57-b069-7ff2a88c1119
description: Customer context object containing customer information.
Error:
type: object
properties:
code:
type: string
description: The error code as a result of the error.
example: ERR001
message:
type: string
description: The error message to provide more context for the error.
example: Invalid input
description: An object containing the error code and message.
Promotion:
type: object
properties:
id:
type: string
description: The unique identifier of the promotion.
example: 6626c179627d450008a5b202
title:
type: string
description: Promotion title
example: Cart Promotion Fixed Price
type:
type: string
description: The type of promotion, such as percentage or fixed value.
example: QUANTITY
value:
type: number
format: float
description: The value of the promotion, indicating the amount of the discount applied. This can be a fixed amount or a percentage.
example: 10
attributes:
type: object
additionalProperties:
type: string
description: Custom attributes provide more context for the promotion.
example:
promotionStack: HIGHEST
ItemFulfillment:
type: object
properties:
id:
type: string
description: The identifier of the fulfillment linked to the item.
example: 6d65755f-b1d9-4c9d-bb5b-118d317f8db4
price:
$ref: '#/components/schemas/ResourcePrice'
inventory:
$ref: '#/components/schemas/Inventory'
tax:
$ref: '#/components/schemas/TaxCollection'
description: Item Fulfillment
PaymentCollection:
type: object
properties:
authorized:
type: number
description: The payments that have been authorized within the collection.
example: 800
collection:
type: array
description: An array containing payments within the collection.
items:
$ref: '#/components/schemas/Payment'
description: An object containing a collection of payments added to the cart.
FulfillmentPromotion:
type: object
properties:
id:
type: string
description: Identifier of a promotion
example: bb44db95-6fbd-4eed-a1ed-4d99bc91250f
amount:
type: number
description: The discount amount applied to a fulfillment.
example: 15
description: Fulfillment Promotion
FulfillmentPromotionCollection:
type: object
properties:
total:
type: number
description: The total discount applied within a collection.
example: 15
collection:
type: array
description: An array containing the promotions within a collection.
items:
$ref: '#/components/schemas/FulfillmentPromotion'
description: A collection of promotions applied to the fulfillment.
OrchestrationError:
type: object
properties:
type:
type: string
example: NOT_FOUND
message:
type: string
example: 404 Not Found from POST https://api.fabric.inc/carts/326949f9-7c25-4983-9848-b2061abb217dl/items/batch
code:
type: integer
example: 404
source:
type: string
example: POST https://api.fabric.inc/carts/326949f9-7c25-4983-9848-b2061abb217dl/items/batch
details:
$ref: '#/components/schemas/ErrorDetails'
Fee:
type: object
properties:
id:
type: string
description: 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.
example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
name:
type: string
description: Name of the fee
example: Eco Fee
price:
$ref: '#/components/schemas/ResourcePrice'
taxable:
type: boolean
description: A boolean value that determines whether a fee is taxable.
example: true
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes that provide more context for the fee, such as the source of the fee.
example:
source: eco
description: Custom attributes that provide more context for the fee, such as the source of the fee.
example:
source: eco
tax:
$ref: '#/components/schemas/TaxCollection'
updatedAt:
type: string
description: The date and time when the fee was last updated.
example: 2024-06-13 16:50:00.682000+00:00
createdAt:
type: string
description: The date and time when the fee was created.
example: 2024-06-13 16:50:00.682000+00:00
taxDetails:
$ref: '#/components/schemas/FeeTaxDetails'
description: A collection of fees associated with the cart.
Attributes:
type: object
description: Custom attributes used to describe the cart, such as a wishlist cart.
additionalProperties:
type: string
example:
attr1: attrValue
Inventory:
type: object
properties:
channels:
type: object
properties:
type:
type: string
description: Channel type (e.g., WEB_PICKUP, WEB_SHIP)
example: WEB_PICKUP
locationNumber:
type: string
description: Location number
example: '15'
channelId:
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.
example: '12'
networkCode:
type: string
description: Network code (for shipping channels)
example: shipToHome
type:
type: string
description: Inventory type (e.g., availableToPurchase, availablePreorder)
example: availableToPurchase
UnprocessableOrchestrationError:
type: object
properties:
type:
type: string
example: UNPROCESSABLE_ORCHESTRATION
message:
type: string
example: 4xx Error from orchestration dependency
errors:
type: array
items:
$ref: '#/components/schemas/OrchestrationError'
Adjustment:
type: object
properties:
id:
type: string
description: The Adjustment ID generated when an adjustment was created using the [Create adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint.
example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
price:
$ref: '#/components/schemas/ResourcePrice'
reason:
type: string
description: The reason for the adjustment.
example: Price adjustment from customer representative.
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes used for price adjustments.
example:
source: CSR
description: Custom attributes used for price adjustments.
example:
source: CSR
updatedAt:
type: string
description: The date and time when the adjustment was last updated.
example: 2024-06-13 16:50:00.682000+00:00
createdAt:
type: string
description: The date and time when the adjustment was created.
example: 2024-06-13 16:50:00.682000+00:00
description: A collection of adjustments made to the cart.
ErrorDetails:
type: object
properties:
type:
type: string
example: CART_NOT_FOUND
message:
type: string
example: Cart not found
errors:
type: array
items:
type: string
example: []
OrderDraftItemRequest:
required:
- id
type: object
properties:
id:
type: string
description: The unique identifier of the item.
example: 6d65755f-b1d9-4c9d-bb5b-118d317f8db4
supplementaryData:
type: object
additionalProperties:
type: object
description: Additional data for the item, such as product attributes.
example:
productTitle: Lamp
description: Additional data for the item, such as product attributes.
example:
productTitle: Lamp
description: Custom data for the item
Tax:
type: object
properties:
amount:
type: number
description: Tax amount
example: 3
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes to provide more context to the tax, such as the rate and the type of tax.
example:
rate: '5.0'
type: COUNTY
description: Custom attributes to provide more context to the tax, such as the rate and the type of tax.
example:
rate: '5.0'
type: COUNTY
description: Tax
Fulfillment:
type: object
properties:
id:
type: string
description: The Fulfillment ID generated when a fulfillment was created using the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint.
example: d6229cdb-0c5b-4885-b1b2-13b94d02488e
type:
type: string
description: Determines the type of fulfillment.
example: SHIP_TO
enum:
- SHIP_TO
- BOPIS
- ROPIS
refId:
type: string
description: An alternative identifier for fulfillments, used for additional tracking or referencing.
example: '398427903843'
attributes:
type: object
description: Custom attributes to provide more context to the fulfillment, such as where it was made.
additionalProperties:
type: object
d
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-orderdrafts-api-openapi.yml