openapi: 3.0.1
info:
title: Cart Actions Endpoints Cancellations 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:
- description: These endpoints check eligibility of order cancellation requests and if eligible, processes order cancellation.
name: Cancellations
paths:
/orders/order-number/{orderNumber}/actions/cancel:
post:
description: "Cancels an order when a customer's cancellation request is determined to be eligible. \nThis endpoint processes the cancellation based on the provided **order number**. \n\n**Note:** \n- Use this endpoint only if you have the order number. \n- If you have the order ID or external order ID instead, use the corresponding \n identifier-based endpoint: `POST /orders/{orderIdType}/{orderIdValue}/actions/cancel`.\n"
operationId: cancelOrderByOrderNumber
parameters:
- description: Merchant-defined order identifier
example: 123k4h123k
in: path
name: orderNumber
required: true
schema:
type: string
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orderCancellationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/orderResponse'
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'400':
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'401':
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'404':
content:
application/json:
example:
message: Order not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'412':
content:
application/json:
example:
message: Order can't be cancelled as there is no line item available for cancellation
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Precondition failed
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'500':
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
summary: Cancel Order by Order Number
tags:
- Cancellations
/orders/order-number/{orderNumber}/actions/check-cancel-eligibility:
post:
description: 'Either customer may initiate cancellation due to an incorrect order placement or as a merchant, you may initiate cancellation due to product unavailability, pricing errors, payment failure, or shipping restrictions. Before processing cancellation, its crucial to determine the eligibility of the cancellation request. <p> This endpoint gets the eligibility of the cancellation request by order number. You can additionally specify `lineItemIds` to get the eligibility of specific line items.</p> <p> **Note**: If you do not have order number, use the corresponding order ID-based endpoint - `/orders/{orderId}/actions/check-cancel-eligibility`.</p>'
operationId: getCancelOrderEligibilityByOrderNumber
parameters:
- description: The merchant-defined order identifier.
example: 123k4h123k
in: path
name: orderNumber
required: true
schema:
type: string
- description: The merchant-defined cancellation policy. When omitted, the default policy is used.
in: query
name: policyName
required: false
schema:
type: string
- description: The line item IDs. If specified, you'll get cancellation eligibility of the given line items. If omitted, you'll get cancellation eligibility of each item in the order.
in: query
name: lineItemIds
required: false
schema:
items:
type: string
type: array
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/eligibilityResponse'
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'400':
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'401':
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'404':
content:
application/json:
example:
message: Not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'500':
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
summary: Get Order Cancellation Eligibility by Order Number
tags:
- Cancellations
/orders/{orderIdType}/{orderIdValue}/actions/cancel:
post:
tags:
- Cancellations
summary: Cancel Order by Order Identifier
description: "Cancels an order when a customer's cancellation request is determined to be eligible. \nThis endpoint processes the cancellation based on the provided order identifier. \n\n**Note:** \n- Use this endpoint if you have the order ID, order number, or external order ID. \n- If you only have an order number, set `orderIdType` to `order-number`.\n"
operationId: cancelOrderByOrderIdentifier
parameters:
- name: orderIdType
in: path
description: "The type of order identifier used to locate the order. \nSupported values: \n- `order-id` \n- `order-number` \n- `order-external-id`\n"
required: true
schema:
type: string
enum:
- order-id
- order-number
- order-external-id
example: order-id
- name: orderIdValue
in: path
description: The value of the specified order identifier.
required: true
schema:
type: string
example: ORDER0001
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orderCancellationRequest'
required: true
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/orderResponse'
'400':
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
type: CLIENT_ERROR
errorCode: SERVICE-4003
message: 'Mandatory param(s): `requiredField1` is/are missing'
errors:
- type: CLIENT_ERROR
errorCode: SERVICE-4002
message: Invalid value(s) specified for 'requiredField.field3'
errors: []
context:
service: orders
endpoint: POST /v3/orders
'401':
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
type: CLIENT_ERROR
errorCode: SERVICE-4001
message: Unauthorized request
errors: []
context:
service: orders
endpoint: POST /v3/orders/OrderId_12345
'404':
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
message: Order not found
type: CLIENT_ERROR
'412':
description: Precondition failed
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
message: Order cannot be cancelled as there is no line item available for cancellation
type: CLIENT_ERROR
'500':
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
type: SERVER_ERROR
errorCode: SERVICE-5000
message: Internal server error
errors: []
context:
service: inventories
endpoint: POST /v3/inventories/actions/find-by-geography
/orders/{orderIdType}/{orderIdValue}/actions/check-cancel-eligibility:
post:
tags:
- Cancellations
summary: Check Order Cancellation Eligibility by Order Identifier
description: "Determines whether an order is eligible for cancellation. \n- Customers may initiate cancellations due to incorrect order placement. \n- Merchants may initiate cancellations due to product unavailability, pricing errors, payment failures, or shipping restrictions. \n\nYou can also specify `lineItemIds` to check cancellation eligibility for specific line items. \nIf not provided, eligibility is checked for each item in the order. \n\n**Note:** \n- Use this endpoint if you have the order ID, order number, or external order ID. \n- If you only have an order number, set `orderIdType` to `order-number`.\n"
operationId: checkCancelEligibilityByOrderIdentifier
parameters:
- name: orderIdType
in: path
description: "The type of order identifier used to locate the order. \nSupported values: \n- `order-id` \n- `order-number` \n- `order-external-id`\n"
required: true
schema:
type: string
enum:
- order-id
- order-number
- order-external-id
example: order-id
- name: orderIdValue
in: path
description: The value of the specified order identifier.
required: true
schema:
type: string
example: ORDER0001
- name: policyName
in: query
description: "The merchant-defined cancellation policy to use when evaluating eligibility. \nIf omitted, the default policy is applied.\n"
required: false
schema:
type: string
- name: lineItemIds
in: query
description: "One or more line item IDs. \n- If specified, eligibility is checked only for the given line items. \n- If omitted, eligibility is checked for each item in the order.\n"
required: false
schema:
type: array
items:
type: string
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/eligibilityResponse'
'400':
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
type: CLIENT_ERROR
errorCode: SERVICE-4003
message: 'Mandatory param(s): `requiredField1` is/are missing'
errors:
- type: CLIENT_ERROR
errorCode: SERVICE-4002
message: Invalid value(s) specified for 'requiredField.field3'
errors: []
context:
service: orders
endpoint: POST /v3/orders
'401':
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
type: CLIENT_ERROR
errorCode: SERVICE-4001
message: Unauthorized request
errors: []
context:
service: orders
endpoint: POST /v3/orders/OrderId_12345
'404':
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
message: Not found
type: CLIENT_ERROR
'500':
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
example:
type: SERVER_ERROR
errorCode: SERVICE-5000
message: Internal server error
errors: []
context:
service: inventories
endpoint: POST /v3/inventories/actions/find-by-geography
/orders/{orderId}/actions/cancel:
post:
description: 'When customers order cancellation request is determined to be eligible, this endpoint processes the cancellation by order ID. <p> **Note**: If you do not have the order number, use the corresponding order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/cancel`.</p>'
operationId: cancelOrder
parameters:
- description: 24-character system-generated order ID returned in the response of Create Order - `POST /orders` endpoint.
example: 5349b4ddd2781d08c09890f4
in: path
name: orderId
required: true
schema:
type: string
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orderCancellationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/orderResponse'
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'400':
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'401':
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'404':
content:
application/json:
example:
message: Order not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'412':
content:
application/json:
example:
message: Order can't be cancelled as there is no line item available for cancellation
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Precondition failed
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'500':
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
summary: Cancel Order by Order ID
tags:
- Cancellations
/orders/{orderId}/actions/check-cancel-eligibility:
post:
description: "Determines whether an order is eligible for cancellation. \n- Customers may initiate cancellation due to incorrect order placement. \n- Merchants may initiate cancellation due to product unavailability, pricing errors, \n payment failures, or shipping restrictions. \n\nThis endpoint checks cancellation eligibility using the **order ID**. \nYou can also specify `lineItemIds` to check eligibility for specific line items. \nIf omitted, eligibility is checked for each item in the order. \n\n**Note:** \n- Use this endpoint only if you have the order ID. \n- If you have an order number instead, use the order number–based endpoint: \n `POST /orders/order-number/{orderNumber}/actions/check-cancel-eligibility`.\n"
operationId: getCancelOrderEligibility
parameters:
- description: 24-character system-generated order ID returned in the response of Create Order - `POST /orders` endpoint.
example: 5349b4ddd2781d08c09890f4
in: path
name: orderId
required: true
schema:
type: string
- description: Merchant-defined cancellation policy. When omitted, the default policy is considered.
in: query
name: policyName
required: false
schema:
type: string
- description: Line item IDs. If specified, gets eligibility of exchange for the given line items. If omitted, gets eligibility of exchange for each item in the order.
in: query
name: lineItemIds
required: false
schema:
items:
type: string
type: array
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/eligibilityResponse'
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'400':
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'401':
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'404':
content:
application/json:
example:
message: Not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'500':
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
summary: Get Order Cancellation Eligibility by Order ID
tags:
- Cancellations
components:
schemas:
orderCancellationRequest:
description: Order cancellation request
properties:
attributes:
description: Merchant-defined custom attributes. This is a placeholder for additional info (in key-value pairs).
example:
isPerishable: 'false'
type: object
employeeId:
description: Employee (ID or name) who initiated the order cancellation request
example: '12312232'
type: string
items:
description: Cancellation request
items:
$ref: '#/components/schemas/orderCancelLineItem'
type: array
note:
description: Additional notes, if any
example: This is a note
type: string
policyCode:
description: Merchant-defined policy code, varies from merchant to merchant. If omitted, the default policy is used.
example: RC1
type: string
reasonCode:
description: Reason code for cancellation, varies from merchant to merchant
example: Incorrect order
type: string
releaseSoftReservation:
type: boolean
source:
description: Merchant-defined source from where the cancellation request was initiated. There are no pre-defined values; possible values could be Customer Service Representative (CSR), point-of-sale (POS), etc.
example: CSR
type: string
subReasonCode:
description: Subreason code for order cancellation, for another layer of classification
example: Incorrect specification
type: string
requestContext:
$ref: '#/components/schemas/requestReferenceContextResource'
description: Request reference context information
required:
- reasonCode
type: object
amountInCurrency:
description: Amount in currency object details.
properties:
amount:
description: The amount displayed in the primary currency.
example: 123.45
format: double
type: number
currency:
description: Currency in ISO-4217
example: USD
type: string
group:
description: A unique identifier for currencies. All calculations and invoicing are based on this identifier. For example, the `Shopper` group uses USD, while the `Retailer` group uses EUR.
example: SHOPPER
type: string
required:
- currency
- group
type: object
quantityInStatus:
description: Item quantity for each status
properties:
cancelled:
description: Cancelled quantity of given item
example: 10
format: int32
type: integer
created:
description: Ordered quantity of given item
example: 10
format: int32
type: integer
delivered:
description: Delivered quantity of given item
example: 10
format: int32
type: integer
hold:
description: Held quantity of given item
example: 10
format: int32
type: integer
pendingShipped:
description: Pending quantity of given item
example: 10
format: int32
type: integer
returned:
description: Returned quantity of given item
example: 10
format: int32
type: integer
shipped:
description: Shipped quantity of given item
example: 10
format: int32
type: integer
type: object
trackingDetailsResource:
type: object
description: Tracking details
properties:
trackingNumber:
type: string
description: Tracking number
example: 1ZH4E331YW37690225
trackingURL:
type: string
description: Tracking URL
example: https://www.ups.com/track?tracknum=1ZH4E331YW37690225
orderDiscount:
description: An object containing all the discount details for an order.
properties:
amount:
description: Discounted amount for the given `quantity` within an order.
example: 2.99
format: double
type: number
amountInCurrencies:
items:
description: Discounted amount for the given `quantity`, itemized by each currency used within the order.
$ref: '#/components/schemas/amountInCurrencyResource'
type: array
invoiceQuantity:
description: Total quantity invoiced. If customer placed order for 10 quantity of an item and only 2 got shipped, then 2 is the `invoiceQuantity`.
example: 10
format: int32
type: integer
promotionCode:
description: Promotion code used by shoppers to take advantage of an ongoing promotion.
example: HNY2022
type: string
promotionId:
description: Unique promotion ID either from fabric Offers service or external Offers service. When fabric Offers service is used, this is the 24-character system-generated promotion ID returned in the response of create promotion endpoint.
example: HNY2022
type: string
promotionName:
description: Promotion name
example: New Year
type: string
quantity:
description: Number of discounted items in an order such as buy 2 get 1 free. In this case 1 is the discounted quantity.
example: 1
format: int32
type: integer
unit:
description: Indicates whether the discount is in amount or percentage
example: AMOUNT_OFF
type: string
value:
description: Value corresponding to `unit`
example: 10
format: int32
type: integer
type: object
refundDetailResource:
description: Used for credit rules. This resource captures the split of fees and tax refunds at the item and order level.
properties:
amount:
description: Refund Amount
example: '-10.'
format: double
type: number
amountInCurrencies:
items:
description: The total refund amount, itemized by each currency used within the order.
$ref: '#/components/schemas/a
# --- truncated at 32 KB (122 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-cancellations-api-openapi.yml