openapi: 3.0.1
info:
title: Cart Actions Endpoints Returns 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 return or exchanges requests and, if eligible, processes order return or exchanges.
name: Returns
paths:
/orders/{orderIdType}/{orderIdValue}/actions/submit-return-request:
post:
tags:
- Returns
summary: Submit Return Request by Order Identifier
description: "Submits a return request for an order once it has been determined that the \ncustomer's return request is eligible. \nThis endpoint processes the return request using the specified order identifier. \n\n**Note:** \n- Use this endpoint if you have the order number or external order ID. \n- If you only have an order number, set `orderIdType` to `order-number`. \n- If you only have an external order ID, set `orderIdType` to `order-external-id`.\n"
operationId: submitReturnRequestByOrderIdentifier
parameters:
- name: orderIdType
in: path
description: "The type of order identifier used to locate the order. \nSupported values: \n- `order-number` \n- `order-external-id`\n"
required: true
schema:
type: string
enum:
- order-number
- order-external-id
example: order-external-id
- name: orderIdValue
in: path
description: The value of the specified order identifier.
required: true
schema:
type: string
example: bef5680-u1245678
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/orderReturnRequest'
required: true
responses:
'201':
description: Return request accepted
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/returnOrderResponse'
'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"" }'
'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-exchange-eligibility:
post:
tags:
- Returns
summary: Check Order Exchange Eligibility by Order Identifier
description: "Determines whether an item or order is eligible for exchange. \nCustomers may request an exchange due to size, fit, color, or style preferences. \nThis endpoint verifies eligibility according to your defined business policies. \n\nYou can also specify a `lineItemId` to check exchange eligibility for a specific \nitem. If omitted, eligibility is checked for each item in the order. \n\n**Note:** \n- Use this endpoint if you have the order number or external order ID. \n- If you only have an order number, set `orderIdType` to `order-number`. \n- If you only have an external order ID, set `orderIdType` to `order-external-id`.\n"
operationId: checkExchangeEligibilityByOrderIdentifier
parameters:
- name: orderIdType
in: path
description: "The type of order identifier used to locate the order. \nSupported values: \n- `order-number` \n- `order-external-id`\n"
required: true
schema:
type: string
enum:
- order-number
- order-external-id
example: order-external-id
- name: orderIdValue
in: path
description: The value of the specified order identifier.
required: true
schema:
type: string
example: bef5680-u1245678
- name: policyName
in: query
description: "The merchant-defined exchange policy to apply. \nIf omitted, the default policy is used.\n"
required: false
schema:
type: string
example: RETURNS_POLICY_1
- name: lineItemId
in: query
description: "A single line item ID. \n- If specified, eligibility is checked only for that item. \n- If omitted, eligibility is checked for each item in the order.\n"
required: false
schema:
type: string
example: 62f3dfc438bcab1951be0a19
- $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: Order with <orderId> is 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/{orderIdType}/{orderIdValue}/actions/check-return-eligibility:
post:
tags:
- Returns
summary: Check Return Eligibility by Order Identifier
description: "Determines whether one or more items in an order are eligible for return. \nCustomers may request a return because items did not meet expectations or \nthey simply changed their mind. \n\nThis endpoint verifies eligibility according to your defined return policies. \nYou can also specify a `lineItemId` to check return eligibility for a specific \nitem. If omitted, eligibility is checked for each item in the order. \n\n**Note:** \n- Use this endpoint if you have the order number or external order ID. \n- If you only have an order number, set `orderIdType` to `order-number`. \n- If you only have an external order ID, set `orderIdType` to `order-external-id`.\n"
operationId: checkReturnEligibilityByOrderIdentifier
parameters:
- name: orderIdType
in: path
description: "The type of order identifier used to locate the order. \nSupported values: \n- `order-number` \n- `order-external-id`\n"
required: true
schema:
type: string
enum:
- order-number
- order-external-id
example: order-external-id
- name: orderIdValue
in: path
description: The value of the specified order identifier.
required: true
schema:
type: string
example: bef5680-u1245678
- name: policyName
in: query
description: "The merchant-defined return policy to apply. \nIf omitted, the default policy is used.\n"
required: false
schema:
type: string
example: RETURNS_POLICY_1
- name: lineItemId
in: query
description: "A single line item ID. \n- If specified, eligibility is checked only for that item. \n- If omitted, eligibility is checked for each item in the order.\n"
required: false
schema:
type: string
example: b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569
- $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: Order 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/order-number/{orderNumber}/actions/check-exchange-eligibility:
post:
description: "Determines whether an order or specific items within an order are eligible for exchange. \nCustomers may request an exchange due to size, fit, color, or style preferences. \nThis endpoint checks exchange eligibility using the **order number**. \n\nYou can also specify a `lineItemId` to check eligibility for a specific item. \nIf omitted, eligibility is checked for each item in the order. \n\n**Note:** \n- Use this endpoint only if you have the order number. \n- If you have an order ID instead, use the identifier-based endpoint: \n `POST /orders/{orderIdType}/{orderIdValue}/actions/check-exchange-eligibility`.\n"
operationId: getOrderExchangeEligibilityByOrderNumber
parameters:
- description: Merchant-defined order identifier
example: Order-320000001
in: path
name: orderNumber
required: true
schema:
type: string
- description: Merchant-defined exchange policy. When omitted, the default policy is considered.
example: RETURNS_POLICY_1
in: query
name: policyName
required: false
schema:
type: string
- description: Line item ID. If specified, gets exchange eligibility of the given line item. If omitted, gets exchange eligibility of each item in the order.
example: 62f3dfc438bcab1951be0a19
in: query
name: lineItemId
required: false
schema:
type: string
- $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: Order with <orderId> is 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 Exchange Eligibility by Order Number
tags:
- Returns
/orders/order-number/{orderNumber}/actions/check-return-eligibility:
post:
description: "Determines whether one or more items in an order are eligible for return. \nCustomers may request a return if items do not meet expectations or if they \nhave simply changed their mind. \nThis endpoint checks return eligibility using the **order number**. \n\nYou can also specify a `lineItemId` to check eligibility for a specific item. \nIf omitted, eligibility is checked for each item in the order. \n\n**Note:** \n- Use this endpoint only if you have the order number. \n- If you have an order ID instead, use the identifier-based endpoint: \n `POST /orders/{orderIdType}/{orderIdValue}/actions/check-return-eligibility`.\n"
operationId: getOrderReturnsEligibilityByOrderNumber
parameters:
- description: Merchant-defined order identifier
example: Order-320000001
in: path
name: orderNumber
required: true
schema:
type: string
- description: Merchant-defined return policy. When omitted, the default policy is considered.
example: RETURNS_POLICY_1
in: query
name: policyName
required: false
schema:
type: string
- description: Line item ID. If specified, you'll get the return eligibility of the given line item ID. If omitted, you'll get the return eligibility of each item in the order.
example: b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569
in: query
name: lineItemId
required: false
schema:
type: string
- $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: Order 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 Return Eligibility by Order Number
tags:
- Returns
/orders/order-number/{orderNumber}/actions/submit-return-request:
post:
description: 'When the customers return request is determined to be eligible, this endpoint is used to process the return request. <p> **Note**: If you do not have the order number, but have order ID, use Return order by order ID endpoint - `POST /orders/{orderId}/actions/submit-return-request`.</p>'
operationId: returnsOrderByOrderNumber
parameters:
- description: Merchant-defined order identifier
example: Order-20000001
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/orderReturnRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/returnOrderResponse'
description: Return request accepted
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'
'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: Order Return by Order Number
tags:
- Returns
/orders/{orderId}/actions/check-exchange-eligibility:
post:
description: 'Customers may want exchange an item because of size, color, or style preferences. Before processing exchange, its crucial to verify whether the item is eligible for exchange as per your policy. <p> This endpoint gets the eligibility of exchange request by order number. You can additionally specify `lineItemId` to get eligibility of a specific item.</p> <p> **Note**: If you do not have the order ID, but have the order number, use the order number-based endpoint - `POST /orders/order-number/{orderNumber}/actions/check-exchange-eligibility`.</p>'
operationId: getOrderExchangeEligibilityByOrderId
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 exchange policy. When omitted, the default policy is considered.
example: RETURNS_POLICY_1
in: query
name: policyName
required: false
schema:
type: string
- description: Line item ID. If specified, gets exchange eligibility of the given line item ID. If omitted, gets exchange eligibility of each item in the order.
example: 62f3dfc438bcab1951be0a19
in: query
name: lineItemId
required: false
schema:
type: string
- $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: Order with orderId is 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 Exchange Eligibility by Order ID
tags:
- Returns
/orders/{orderId}/actions/check-return-eligibility:
post:
description: "Determines whether one or more items in an order are eligible for return. \nCustomers may request a return if items do not meet expectations or if they \nhave simply changed their mind. \n\nThis endpoint checks return eligibility using the **order ID**. \nYou can also specify a `lineItemId` to check eligibility for a specific item. \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-return-eligibility`.\n"
operationId: getOrderReturnsEligibilityByOrderId
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 return policy. When omitted, the default policy is considered.
example: RETURNS_POLICY_1
in: query
name: policyName
required: false
schema:
type: string
- description: Line item ID. If specified, gets the return eligibility of the given line item ID. If omitted, gets the return eligibility of each item in the order.
example: b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569
in: query
name: lineItemId
required: false
schema:
type: string
- $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:
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-returns-api-openapi.yml