components:
headers:
xFabricRequestIdResponseHeader:
description: Unique request ID
example: 263e731c-45c8-11ed-b878-0242ac120002
required: false
schema:
type: string
parameters:
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
xFabricChannelIdOptional:
description: >-
x-fabric-channel-id identifies the sales channel through which the API
request is being made; primarily for multichannel use cases. It is an
optional field. The default US channel is 12 while the default Canada
channel is 13.
example: '12'
in: header
name: x-fabric-channel-id
required: false
schema:
type: string
xFabricChannelIds:
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. A comma separated list of
sales channel IDs. This comma separated list of sales channel IDs are
required when using multiple channels.
example: 12, 13, 16
in: header
name: x-fabric-channel-ids
required: false
schema:
type: string
xFabricChannelIdsOptional:
description: >-
x-fabric-channel-id identifies the sales channel through which the API
request is being made; primarily for multichannel use cases. It is an
optional field. The default US channel is 12 while the default Canada
channel is 13. This field is optional. **Note:** Use `xFabricChannelIds`
for multiple channels, and `xFabricChannelId` for a single channel.
example: 12, 13, 16
in: header
name: x-fabric-channel-ids
required: false
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
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
schemas:
acknowledgePackageTrackingRequest:
description: Acknowledgement for package tracking
properties:
attributes:
additionalProperties:
description: Additional custom attribute mappings.
type: object
description: A list of custom mapped attributes.
type: object
eventType:
description: Event type for which acknowledgement is received
enum:
- ORDER_CREATE_IN_PTS
- ORDER_CANCELLED_IN_PTS
- SHIPMENT_CREATE_IN_PTS
- SHIPMENT_CANCELLED_IN_PTS
- TRANSFER_CREATE_IN_PTS
- TRANSFER_CANCELLED_IN_PTS
- TRANSFER_SHIPMENT_CREATE_IN_PTS
- TRANSFER_SHIPMENT_CANCELLED_IN_PTS
example: ORDER_CREATE_IN_PTS
type: string
required:
- eventType
type: object
address:
description: Address details
properties:
addressLine1:
description: Address line 1
example: 123 Main St.
type: string
addressLine2:
description: Address line 2
example: Suite 100
type: string
addressLine3:
description: Address line 3
example: Seventh floor
type: string
addressLine4:
description: Address line 4
example: 'Attention: Pat E. Kake'
type: string
city:
description: City name
example: Seattle
type: string
countryCode:
description: ISO 3166-1 alpha-2 based country code
example: US
type: string
email:
description: Contact person's email
example: [email protected]
type: string
latitude:
description: >-
Address latitude, used with `longitude` to specify the address
location. Decimal degrees format; negative is degrees South.
**Note:**Value must be between -90 and 90, both inclusive.
example: 47.6205
format: double
type: number
longitude:
description: >-
Address longitude, used with `latitude` to specify the address
location. Decimal degrees format; negative is degrees South.
**Note:**Value must be between -180 and 180, both inclusive.
example: -122.3493
format: double
type: number
name:
$ref: '#/components/schemas/orderContactName'
phone:
$ref: '#/components/schemas/orderContactPhone'
postalCode:
description: Postal or ZIP code
example: '98121'
type: string
region:
description: Region or state
example: WA
type: string
type:
description: Address type
example: Home
type: string
required:
- addressLine1
- city
- countryCode
- latitude
- longitude
- postalCode
- region
- type
type: object
amountInCurrencyResource:
type: object
description: Amount in currency details
properties:
currency:
type: string
description: Currency in ISO-4217
example: USD
group:
type: string
description: 'Customer defined function name which uses this currency. '
example: SHOPPER
amount:
type: number
format: double
description: Amount in currency
example: 123.45
required:
- currency
- group
baseGiftCardDetails:
type: object
description: Base gift card details
properties:
giftCardNumber:
type: string
description: Gift card number
example: 453456765
amount:
type: number
format: double
description: Gift card amount
example: 50
amountInCurrencies:
type: array
items:
$ref: '#/components/schemas/amountInCurrencyResource'
baseScratchedItemDetails:
type: object
description: Base details of items scratched (removed) from a shipment.
properties:
orderId:
type: string
description: >-
System-generated 24-character order ID, returned in the response of
the Create Order endpoint (`POST /orders`).
example: 6413e370cb0dc859b6c0dcb0
orderNumber:
type: string
description: Merchant-defined order number associated with the shipment.
example: 309020213
orderExternalId:
type: string
description: >-
External order identifier defined by the merchant. Useful for
reconciliation with external systems.
example: 123k4h123k
lineItemId:
type: string
description: >-
Unique identifier for the line item in the order. If not provided,
fabric automatically generates this value in UUID format during
order creation.
example: 2
itemId:
type: integer
format: int32
description: System-generated unique identifier for the item.
example: 100043
sku:
type: string
description: >-
Stock keeping unit (SKU), a merchant-defined unique identifier for
the item.
example: SKU00043
quantity:
type: integer
format: int32
default: 0
description: Number of units scratched from the shipment.
example: 1
uom:
type: string
description: >-
Unit of measure for the item (for example, EA for Each, GAL for
Gallon, DZ for Dozen).
example: EA
reasonCode:
type: string
description: >-
Code indicating the primary reason for scratching the item from the
shipment.
example: ReasonCode23454
subReasonCode:
type: string
description: >-
Code indicating a more specific sub-reason related to the scratch
action.
example: SubReasonCode23242
attributes:
type: object
description: >-
Merchant-defined custom attributes in key-value format. Useful for
adding supplemental information.
example:
attribute1: value
required:
- lineItemId
- quantity
- reasonCode
cartonDetails:
description: Carton details
properties:
cartonNumber:
description: >-
Merchant-defined unique identifier. This can optionally be generated
by fabric by using the resource generator feature of the
Configuration service.
example: '1'
type: string
cartonType:
description: Carton type
example: Package
type: string
estimatedDeliveryDate:
description: >-
Estimated delivery date given by carrier (UTC). It's based on
several factors including selected shipping method and delivery
location.
example: '2023-03-26T07:58:30.996Z'
format: date-time
type: string
estimatedShipDate:
description: Estimated ship date given by carrier (UTC)
example: '2023-03-25T07:58:30.996Z'
format: date-time
type: string
items:
description: Item
items:
$ref: '#/components/schemas/cartonItems'
type: array
promisedDeliveryDate:
description: Promised delivery date given by seller (UTC)
example: '2023-03-26T07:58:30.996Z'
format: date-time
type: string
shipmentCarrier:
description: Shipment carrier
example: FEDEX
type: string
shipmentMethod:
description: Shipment method
example: ground
type: string
tracking:
description: Tracking details
items:
$ref: '#/components/schemas/trackingResource'
type: array
trackingNumber:
description: >-
Merchant-defined shipment tracking number for the given carton. Used
for tracking shipment, also for updating tracking status of given
carton.
example: 1Z999AA10123456784
type: string
trackingURL:
description: Shipment tracking URL for the given carton
example: https://fedex.com/tracking
type: string
weight:
description: Carton weight
example: 500 gram
type: string
type: object
cartonItems:
description: Item details
properties:
attributes:
description: >-
Merchant-defined custom attributes. This is a placeholder for
addition info (in key: value pairs)
example:
attribute1: value
type: object
fees:
description: Return fee details
items:
$ref: '#/components/schemas/returnFeeDetail'
type: array
giftCards:
description: Gift card details
items:
$ref: '#/components/schemas/giftCardDetails'
type: array
itemId:
description: Unique item identifier from fabric Products service
example: 100023
format: int32
type: integer
lineItemId:
description: >-
Unique number assigned by merchant to identify each item in an
order. When this value isn't provided, fabric will auto generate (in
UUID format) during order creation.
example: '1'
type: string
orderId:
description: >-
24-character system-generated ID displayed in the response of Create
Order endpoint - `POST /orders`
example: 6413e370cb0dc859b6c0dcb0
type: string
orderNumber:
description: Merchant-defined order identifier
example: '309020213'
type: string
shipmentExternalId:
type: string
description: >-
Unique shipment identifier defined by the merchant. This value can
be used to track or reconcile shipments in external systems and
serves as a reference between fabric and the merchant's order
management or fulfillment system.
example: 123k4h123k
orderedQuantity:
description: Ordered quantity of given item
example: 2
format: int32
minimum: 0
type: integer
refundAmount:
description: Return amount. Applicable for return shipment scenarios.
example: 10
format: double
type: number
refundAmountInCurrencies:
type: array
description: >
The return amount represented in one or more currencies.
Each entry specifies the refunded value and its corresponding
currency code,
following the structure defined in the `amountInCurrencyResource`
schema.
items:
$ref: '#/components/schemas/amountInCurrencyResource'
returnQuantity:
description: >-
Returned quantity of given item. Applicable for return shipment
scenarios.
example: 1
format: int32
minimum: 0
type: integer
returnRequestCounter:
description: >-
Number of times return request is made for the given order.
Applicable only for return shipment scenario.
example: 1
format: int32
type: integer
segment:
description: Item segment
example: segment
type: string
shippedQuantity:
description: Shipped quantity of given item
example: 2
format: int32
minimum: 0
type: integer
sku:
description: Stock keeping unit (SKU), unique item identifier
example: SKU0023
type: string
uom:
description: >-
Unit in which a product is measured or sold. UOM can be set to
'each' (EA) or GAL (Gallon), DZ (Dozen), etc.
example: EA
type: string
vendorId:
description: >-
Vendor ID. Applicable in dropshipping scenarios to indicate the
vendor responsible for the given item.
example: '56'
type: string
required:
- lineItemId
- shippedQuantity
type: object
cartonDetailsBasedOnOrder:
type: object
description: Details of a carton included in a shipment, based on the order.
properties:
cartonNumber:
type: string
description: >-
Unique carton identifier defined by the merchant. This value can
also be auto-generated by fabric using the resource generator
feature in the Configuration service.
example: 1
cartonType:
type: string
description: >-
Type of carton used for shipping (for example, Package, Pallet,
Crate).
example: Package
promisedDeliveryDate:
type: string
format: date-time
description: Promised delivery date provided by the seller (in UTC).
example: '2023-03-26T07:58:30.996Z'
estimatedShipDate:
type: string
format: date-time
description: Estimated ship date provided by the carrier (in UTC).
example: '2023-03-25T07:58:30.996Z'
estimatedDeliveryDate:
type: string
format: date-time
description: >-
Estimated delivery date provided by the carrier (in UTC). Determined
by factors such as the selected shipping method and delivery
location.
example: '2023-03-26T07:58:30.996Z'
shipmentMethod:
type: string
description: >-
Shipping method selected for the carton (for example, Ground, Air,
2-Day).
example: ground
shipmentCarrier:
type: string
description: >-
Carrier responsible for delivering the carton (for example, FedEx,
UPS).
example: FEDEX
weight:
type: string
description: >-
Weight of the carton. Units should be specified consistently (for
example, pounds or kilograms).
example: 500
trackingNumber:
type: string
description: >-
Tracking number assigned to the carton. Used to monitor shipment
progress and update tracking status.
example: 1Z999AA10123456784
trackingURL:
type: string
description: Direct URL for tracking the carton shipment.
example: https://fedex.com/tracking
tracking:
type: array
description: Tracking history and status updates for the carton.
items:
$ref: '#/components/schemas/trackingResource'
items:
type: array
description: List of items contained within the carton.
items:
$ref: '#/components/schemas/cartonItems'
required:
- items
createShipmentRequest:
description: Details to create shipment
properties:
allocationId:
description: >-
Allocation ID for this shipment, generated by the fabric Allocation
service through Create allocation (internal) endpoint, which occurs
prior to Shipment Creation. This is mandatory to create a new
shipment.
example: '112345678912340'
type: string
attributes:
description: >-
Merchant-defined custom attributes. This is a placeholder for
addition info (in key: value pairs)
example:
attribute1: value
type: object
cartons:
description: Carton details
items:
$ref: '#/components/schemas/cartonDetails'
type: array
invoiceId:
description: >-
Invoice ID generated from fabric Invoice service during shipment
creation. **Note**: Invoices are only created for Shipments where
merchants have payment **Capture at Shipment** feature enabled. The
value will be “Null” if merchants don't have “Capture at Shipment”
feature enabled.
example: 63ef4360aafa8a7f5247fe48
type: string
locationNumber:
description: >-
Unique value to identify ship-from location. This must be the
`locationNumber` stored in the fabric Location service.
example: WH334
type: string
locationType:
description: >-
Location type, such as distribution center (DC) or warehouse. This
must be the type stored in the fabric Location service.
example: DC
type: string
masterTrackingNumber:
description: Master tracking number for all cartons in the shipment
example: TX112345678
type: string
poNumber:
description: Merchant-defined purchase order number
example: '1125'
type: string
recipients:
description: Recipient details
items:
$ref: '#/components/schemas/shipmentRecipient'
type: array
reshipmentReasonCode:
description: Reshipment reason code
example: Order is missing
type: string
scratchedItems:
description: Scratched items
items:
$ref: '#/components/schemas/scratchedItemDetails'
type: array
shipToAddress:
$ref: '#/components/schemas/address'
shipToId:
description: >-
Ship-to ID generated in the response of Create Shipping endpoint of
Shipping service
example: sg6683620405
type: string
shipmentId:
description: Shipment's autogenerated unique id
example: 627963716b19511e8a3a631b
type: string
shipmentNumber:
description: Merchant-defined shipment identifier
example: '78974156816152'
type: string
shipmentExternalId:
type: string
description: >-
Unique shipment identifier defined by the merchant. This value can
be used to track or reconcile shipments in external systems and
serves as a reference between fabric and the merchant's order
management or fulfillment system.
example: 123k4h123k
shippedAt:
description: Order shipment time (UTC)
example: '2023-04-06T07:58:30.996Z'
format: date-time
type: string
statusCode:
description: >-
Current shipment status (fabric-defined codes). For standard
shipments, the initial status would be SHIPMENT_CREATED. For pickup
shipment, the initial status would be PICKUP_CREATED and once the
customer picks up, the status changes to PICKUP_COMPLETED
enum:
- SHIPMENT_CREATED
- SHIPMENT_UPDATED
- SHIPMENT_CANCELLED
- PICKUP_CREATED
- PICKUP_COMPLETED
- SHIPMENT_RETURN_PENDING
- SHIPMENT_RETURN_RECEIVED
- SHIPMENT_PARTIALLY_DELIVERED
- SHIPMENT_DELIVERED
- SHIPMENT_ERROR
example: SHIPMENT_CREATED
type: string
subtype:
description: >-
Shipment subtype. Free-form text to add another layer of
classification, if required.
example: COD
type: string
totalCartons:
description: Total number of cartons in the given shipment.
example: 2
format: int32
type: integer
type:
description: Shipment types
enum:
- STANDARD
- RESHIP
- RETURN
- SCRATCH
- PENDING_RETURN
- PICKUP
- TRANSFER
example: STANDARD
type: string
vendorId:
description: >-
Vendor ID. Applicable in dropshipping scenarios to indicate the
vendor responsible for the given item.
example: '56'
type: string
required:
- allocationId
- shipmentNumber
type: object
createShipmentByOrderRequest:
type: object
description: Request payload to create a shipment for an order.
properties:
shipmentNumber:
type: string
description: Unique shipment identifier defined by the merchant.
example: 78974156816152
shipmentExternalId:
type: string
description: >-
Unique shipment identifier defined by the merchant. This value can
be used to track or reconcile shipments in external systems and
serves as a reference between fabric and the merchant's order
management or fulfillment system.
example: 123k4h123k
poNumber:
type: string
description: Merchant-defined purchase order number associated with the shipment.
example: 1125
vendorId:
type: string
description: >-
Vendor identifier. In dropshipping scenarios, indicates the vendor
responsible for fulfilling the shipment.
example: 56
statusCode:
type: string
description: Current status of the shipment.
enum:
- SHIPMENT_CREATED
- SHIPMENT_UPDATED
- SHIPMENT_CANCELLED
- PICKUP_CREATED
- PICKUP_COMPLETED
- SHIPMENT_RETURN_PENDING
- SHIPMENT_RETURN_RECEIVED
- SHIPMENT_PARTIALLY_DELIVERED
- SHIPMENT_DELIVERED
- SHIPMENT_ERROR
example: SHIPMENT_CREATED
type:
type: string
description: Type of shipment.
enum:
- STANDARD
- RESHIP
- RETURN
- SCRATCH
- PENDING_RETURN
- PICKUP
- TRANSFER
example: STANDARD
subtype:
type: string
description: >-
Free-form text to provide an additional classification for the
shipment, if required.
example: COD
reshipmentReasonCode:
type: string
description: Code indicating the reason for a reshipment.
example: Order is missing
shippedAt:
type: string
format: date-time
description: UTC timestamp indicating when the shipment was created or shipped.
example: '2023-04-06T07:58:30.996Z'
locationNumber:
type: string
description: >-
Identifier of the ship-from location. Must match the
`locationNumber` stored in the fabric Location service.
example: 132412
locationType:
type: string
description: >-
Type of the ship-from location (for example, distribution center
(DC) or warehouse). Must match the value stored in the fabric
Location service.
example: DC
totalCartons:
type: integer
format: int32
description: Total number of cartons included in the shipment.
example: 2
masterTrackingNumber:
type: string
description: >-
Carrier-provided master tracking number that applies to all cartons
in the shipment.
example: TX112345678
shipToId:
type: string
description: >-
Ship-to identifier generated in the response of the Create Shipping
endpoint in the Shipping service.
example: sg6683620405
shipToAddress:
$ref: '#/components/schemas/address'
recipients:
type: array
description: List of recipients for the shipment.
items:
$ref: '#/components/schemas/shipmentRecipient'
attributes:
type: object
description: >-
Merchant-defined custom attributes, represented as key-value pairs.
Useful for storing additional information.
example:
attribute1: value
cartons:
type: array
description: Details of cartons included in the shipment.
items:
$ref: '#/components/schemas/cartonDetailsBasedOnOrder'
scratchedItems:
type: array
description: Details of items marked as scratched from the shipment.
items:
$ref: '#/components/schemas/baseScratchedItemDetails'
required:
- shipmentNumber
errorResponse:
description: Error response
properties:
errors:
description: Errors
items:
$ref: '#/components/schemas/errorResponse'
type: array
message:
description: Error message
example: Bad request
type: string
type:
description: Error type
example: CLIENT_ERROR
type: string
type: object
giftCardActivation:
description: Gift card info
properties:
giftCardNumber:
description: Gift card number
example: '453456765'
type: string
giftCardStatus:
description: Gift card status
enum:
- PENDING_ACTIVATION
- ACTIVE
- FAILED
example: ACTIVE
type: string
required:
- giftCardNumber
- giftCardStatus
type: object
giftCardDetails:
description: Gift card details
properties:
amount:
description: Gift card amount
example: 50
format: double
type: number
giftCardNumber:
description: Gift card number
example: '453456765'
type: string
type: object
giftCardItem:
description: Gift card details
properties:
giftCards:
description: Gift cards
items:
$ref: '#/components/schemas/giftCardActivation'
maxItems: 100
minItems: 1
type: array
shipmentLineItemId:
description: >-
Unique number assigned by merchant to identify item in a shipment.
When this value isn't provided, fabric will auto generate (UUID
format) during shipment.
example: 607f1f77bcf86cd799439011
type: string
required:
- giftCards
- shipmentLineItemId
type: object
giftCardItemsActivationRequest:
description: Gift card activation request
properties:
items:
description: Items
items:
$ref: '#/components/schemas/giftCardItem'
maxItems: 1000
minItems: 1
type: array
required:
- items
type: object
libQuery:
description: Library Query Model
properties:
filters:
additionalProperties:
description: >-
A query used to filter your records. The query structure should
match the target entity ( for example, order, shipment, etc)
structure.
example: |
{
"retail": {
"locationNum": 12
},
"orderSubTotal": {
"lt": 1400
},
"orderNumber": {order-*Z},
"statusCode": [
"ORDER_CREATED"
],
"createdAt":{
"lt": "2022-09-11T23:12:00.123Z"
},
"shipInfo": {
"shipToId": ["23434","23436"]
}
}
type: object
description: >-
A query used to filter your records. The query structure should
match the target entity ( for example, order, shipment, etc)
structure.
example: |
{
"retail": {
"locationNum": 12
},
"orderSubTotal": {
"lt": 1400
},
"orderNumber": {order-*Z},
"statusCode": [
"ORDER_CREATED"
],
"createdAt":{
"lt": "2022-09-11T23:12:00.123Z"
},
"shipInfo": {
"shipToId": ["23434","23436"]
}
}
type: object
limit:
default: 10
description: The maximum number of records per page
# --- truncated at 32 KB (147 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-shipments-openapi.yml