openapi: 3.0.1
info:
title: Cart Actions Endpoints Shipments 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: 'fabric **Shipments** API is a multi-tenant service that enables you to manage shipments for existing ''Allocations.'' Shipments serve as records of the locations from which an order was fulfilled. Typical user of fabric Shipments service is a Warehouse management service or Point of Sale service. <p> **Note**: Shipments API relies on the Allocation service to send allocation details to external merchant systems after an order is placed. Allocation is the prerequisite for using Shipments API.</p>'
name: Shipments
paths:
/shipments:
post:
description: 'To use this endpoint an “allocation” must exist for the order that''s being shipped. When an order is placed, fabric sends allocation details to external merchant system to create order fulfillment requirement details in an external system. With reference to the allocation that''s being shipped, users of this POST API can create shipment details for allocations. <p> **Note**: Shipment ID generated as part of the response is required for subsequent calls such as Acknowledge shipment (`POST /shipments/{shipmentId}/acknowledge`) and Get shipment (`GET /shipments/{shipmentId}`).</p>'
operationId: createShipment
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createShipmentRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentResponse'
description: Created
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'
'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: Create New Shipment
tags:
- Shipments
/shipments/create-order-shipment:
post:
tags:
- Shipments
summary: Create Shipment for an Existing Order
description: "Creates shipment details for an existing order.\n\nThis endpoint can only be used for orders that already exist. When an order is placed, \nfabric sends allocation details to external merchant systems to define fulfillment \nrequirements. Using the provided allocation reference, this endpoint (POST) creates \nshipment records associated with that order.\n\nNote:\n- The Shipment ID returned in the response is required for subsequent calls:\n - Acknowledge shipment: `POST /shipments/{shipmentId}/acknowledge`\n - Get shipment: `GET /shipments/{shipmentId}`\n"
operationId: createShipmentByOrder
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createShipmentByOrderRequest'
required: true
responses:
'201':
description: Created
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentResponse'
'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
'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
/shipments/actions/re-ship:
post:
description: 'Orders may go missing before they''re delivered to customers for reasons such as incorrect address, theft, labelling issues, or other reasons. This endpoint triggers reshipment in such cases for the existing location. <p> **Note**: Shipment ID generated as part of the response is required for subsequent calls such as Acknowledge shipment (POST /shipments/{shipmentId}/acknowledge) and Get shipment (GET /shipments/{shipmentId}).</p>'
operationId: createReshipment
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createShipmentRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentResponse'
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'
'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: Create Re-shipment
tags:
- Shipments
/shipments/actions/update-tracking:
post:
description: The update tracking endpoint creates a new tracking log that can be used to update the order status. The most common application of this endpoint is to connect to external web services or 'adapters' that have been integrated with carrier tracking applications. With this endpoint, fabric Shipment service gets information from carrier tracking applications, and in turn, updates customers about their shipment status.
operationId: updateTrackingDetails
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentTrackingDetail'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentsResponse'
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: Shipment not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Shipment 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: Update Shipment Tracking
tags:
- Shipments
/shipments/search:
post:
description: As merchants, you may want to view shipments of specific statuses, monitor progress of deliveries, and proactively manage situations to ensure timely deliveries. <p> This endpoint enables you to easily search for shipments based on the specified criteria in the request body. You can refine your search by specifying `limit` and `offset`. When they're not specified, by default you will get up to 10 records. In addition, you can `sort` results.</p>
operationId: searchShipments
parameters:
- in: query
name: fetchOnlyIds
required: false
schema:
default: false
type: boolean
- description: The number of records to skip before returning all records. For example, `offset=20, limit=10` returns records 21-30.
example: 0
in: query
name: offset
schema:
default: 0
type: number
- description: Maximum number of records per page.
example: 10
in: query
name: limit
schema:
default: 10
example: 10
type: number
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentsSearchRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentsSearchResponse'
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'
'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: Find Shipments
tags:
- Shipments
/shipments/{shipmentId}:
get:
description: As merchants, you may want to resolve customer queries related to shipment or track a specific shipment to manage customer expectations with timely communication. <p> This endpoint gets details of a single shipment by ID. You will get `shipmentId` by using the search endpoint, or by referencing a `shipmentId` on a file such as the Invoice.</p>
operationId: getShipment
parameters:
- description: 24-character system-generated shipment ID. It's generated in the response of Create Shipment - `POST /shipments` endpoint.
example: 627963716b19511e8a3a631b
in: path
name: shipmentId
required: true
schema:
type: string
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentResponse'
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: Shipment not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Shipment 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 Shipment by ID
tags:
- Shipments
/shipments/{shipmentIdType}/{shipmentIdValue}:
get:
tags:
- Shipments
summary: Get Shipment by Shipmentidtype and Shipmentidvalue
description: 'Retrieves shipment details by `shipmentIdType` and `shipmentIdValue`.
As a merchant, you may need to review or monitor a shipment to address customer
inquiries, resolve complaints, or support analytics and reporting. This endpoint
allows you to access shipment information using the shipment identifiers.
'
operationId: getShipmentByIdAndIdType
parameters:
- name: shipmentIdType
in: path
description: "This field specifies the type of shipment identifier used in the request.\nValid values:\n - shipment-number — The merchant-defined shipment number.\n - shipment-external-id — The merchant-assigned external identifier for the shipment."
required: true
schema:
type: string
enum:
- shipment-number
- shipment-external-id
example: shipment-external-id
- name: shipmentIdValue
in: path
description: 'This field specifies the identifier value that corresponds to the type in `shipmentIdType`.
For example, if `shipmentIdType` is `shipment-number`, then this value must be the merchant-defined shipment number.'
required: true
schema:
type: string
examples:
shipment-number:
summary: Merchant-defined Shipment Number
value: '217088603'
shipment-external-id:
summary: Merchant-assigned External Shipment Identifier
value: bef5680-u1245678
- $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/shipmentResponse'
'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 orderNumber 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
/shipments/{shipmentId}/acknowledge:
post:
description: For users of fabric Webhook Service, Shipment related events can trigger HTTP callbacks to notify web clients through a merchant-defined URL/URI, typically an API Gateway for a middleware. While the response to fabric Webhook service HTTP call-back may occur, a secondary call-back can use this Acknowledge Shipment endpoint to indicate that a secondary external system has acknowledged this shipment event. Middleware receives the event, transforms it in a suitable format, and sends a success response back to fabric, confirming it received the event. It also sends the transformed event to an external merchant system (typically in XML or JSON).<p>With this endpoint, middleware immediately sends an asynchronous acknowledgement to fabric, based on shipping ID, to indicate whether the call was successful. This acknowledgement is used for learning, auditing, and taking any necessary action.</p>
operationId: acknowledgeShipment
parameters:
- description: 24-character system-generated shipment ID. It's generated in the response of Create Shipment - `POST /shipments` endpoint.
example: 627963716b19511e8a3a631b
in: path
name: shipmentId
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/shipmentAcknowledge'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipmentAcknowledgeResponse'
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: Shipment not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Shipment 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: Acknowledge Shipment
tags:
- Shipments
/shipments/{shipmentId}/actions/update-gift-cards-status:
post:
description: This endpoint is used to activate gift cards before they're delivered to the customer. Typically used by “adapters” or external web services integrated with gift card applications, so that gift cards can be activated as part of the fabric fulfillment workflow.
operationId: updateGiftCardStatus
parameters:
- description: 24-character system-generated shipment ID. It's generated in the response of Create Shipment - `POST /shipments` endpoint.
example: 627963716b19511e8a3a631b
in: path
name: shipmentId
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/giftCardItemsActivationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/giftCardItem'
type: array
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: Shipment not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Shipment 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: Update Gift Card Activation Status
tags:
- Shipments
components:
parameters:
xFabricTenantId:
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.
example: 5f328bf0b5f328bf0b5f328b
in: header
name: x-fabric-tenant-id
required: true
schema:
type: string
xFabricRequestId:
description: Unique request ID
example: 263e731c-45c8-11ed-b878-0242ac120002
in: header
name: x-fabric-request-id
required: false
schema:
type: string
xFabricChannelId:
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'
in: header
name: x-fabric-channel-id
required: true
schema:
type: string
schemas:
giftCardActivati
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-shipments-api-openapi.yml