Find shipments

As merchants, you may want to view shipments of specific statuses, monitor progress of deliveries, and proactively manage situations to ensure timely deliveries.

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.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-fabric-tenant-id

string

required

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. This header is required.

x-fabric-channel-id

string

required

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.

x-fabric-request-id

string

Unique request ID

Query Parameters

fetchOnlyIds

boolean

default:

false

offset

number

default:

0

The number of records to skip before returning all records. For example, offset=20, limit=10 returns records 21-30.

limit

number

default:

10

Maximum number of records per page.

Example:

10

Body

application/json

Sort and filter criteria for shipment search

filters

object[]

required

• Option 1
• Option 2

The criteria used to find shipments by a single value. Condition between field and value is anything except IN and NIN when valueSearchFilter is used.

Show child attributes

filters.condition

enum<string>

default:

EQ

required

Filter conditions. EQ (Equal to): Searches for exact match. NEQ (Not equal to): Searches by excluding the specified value. IN: Search for multiple values. NIN (Not IN): Excludes the specified values in the search. LT (Less than): Searches for values that are less than the specified value. GT (Greater than): Search for values that are greater than the specified value. LTE (Less than or equal to): Searches for values that are less than or equal to the specified value. GTE (Greater than or equal to): Searches for values that are greater than or equal to the specified value.

Available options:

EQ,

NEQ,

IN,

NIN,

LT,

GT,

LTE,

GTE

Example:

"LT"

filters.field

string

required

Field name

Example:

"shipment.shipmentNum"

filters.group

string

default:

Default

Group name

Example:

"GroupA"

filters.value

Search criteria using a single value

Example:

"ORDER_CREATE"

sort

string

default:

-shipment.shipDate

Property name on which response needed to be sorted. Note: - refers to descending and + refers to ascending order

Example:

"-shipment.shipDate"

Response

200

application/json

OK

Shipment search response

data

object[]

Shipment details

Show child attributes

data.version

integer

required

The current version of the shipment document. This integer indicates the number of times the shipment has been updated by any operation.

Example:

2

data.allocationId

string

System-generated allocation ID (UUID) from the Create allocation endpoint of fabric Allocation service. It refers to the given shipment. Note: Allocation occurs prior to Shipment Creation. allocationId is mandatory to create a Shipment.

Example:

"6413e3d3fd03a35efccb426e"

data.auditLogs

object[]

Audit log details

Details for updating shipment

Show child attributes

data.auditLogs.auditId

string

System-generated audit ID (UUID format)

Example:

"a05b72dc-78d8-4ea4-90fc-2fe6a1fe1111"

data.auditLogs.auditType

string

Audit type such as cancel, return, etc.

Example:

"CANCEL"

data.auditLogs.auditedAt

string

Audit time (UTC)

Example:

"2023-03-12T09:24:54.804Z"

data.auditLogs.employeeId

string

Employee (ID or name) who made the last update

Example:

"6227"

data.auditLogs.lineItemId

string

Merchant-defined unique identifier for each item in an order. When omitted, fabric will generate it during order creation, in UUID format.

Example:

"b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569"

data.auditLogs.note

string

Additional info, if any

Example:

"Note"

data.auditLogs.reasonCode

string

Merchant-defined reason code, varies from merchant to merchant

Example:

"Scratched item"

data.auditLogs.source

string

Merchant-defined source from where the update was initiated. There are no predefined values; possible values could be Customer Service Representative (CSR), Point-of-Sale (POS), etc.

Example:

"POS"

data.auditLogs.subReasonCode

string

Merchant-defined sub reason code; provides more clarity to audit reason

Example:

"Scratched item"

data.auditLogs.updatedFields

object[]

Audit log for change history

Audit log for change history

Show child attributes

data.auditLogs.updatedFields.fieldName

string

Field or property name that was updated

Example:

"UOM"

data.auditLogs.updatedFields.fieldOriginalValue

string

Original value of fieldName before it was updated

Example:

"PK"

data.cartons

object[]

Carton details

Carton details

Show child attributes

data.cartons.cartonNumber

string

Merchant-defined unique identifier. This can optionally be generated by fabric by using the resource generator feature of the Configuration service.

Example:

"1"

data.cartons.cartonType

string

Carton type

Example:

"Package"

data.cartons.estimatedDeliveryDate

string

Estimated delivery date given by carrier based on several factors including selected shipping method and delivery location (UTC).

Example:

"2023-04-26T07:58:30.996Z"

data.cartons.estimatedShipmentDate

string

Estimated ship date given by seller based on availability of items, their processing time, delivery location, and selected shipping method (UTC).

Example:

"2023-03-25T07:58:30.996Z"

data.cartons.items

object[]

Carton item details

Details of item in shipment

Show child attributes

data.cartons.items.fees

object[]

Fee details

Return fee details

Show child attributes

data.cartons.items.fees.amount

number

Merchant-defined return amount

Example:

34.56

data.cartons.items.fees.name

string

Fee name

Example:

"RETURN_FEE"

data.cartons.items.fees.reason

string

Merchant-defined return reason

Example:

"Return fee"

data.cartons.items.fees.type

enum<string>

Return fee type

Available options:

TAX,

DISCOUNT,

FEE,

ITEM,

ADJUSTMENT

Example:

"FEE"

data.cartons.items.giftCards

object[]

Gift card details

Gift card details

Show child attributes

data.cartons.items.giftCards.amount

number

Gift card amount

Example:

50

data.cartons.items.giftCards.giftCardActivatedAt

string

Time gift card was activated (UTC)

Example:

"2023-04-26T07:58:30.996Z"

data.cartons.items.giftCards.giftCardActivationRequestedAt

string

Time of placing gift card activation request (UTC)

Example:

"2023-03-26T07:58:30.996Z"

data.cartons.items.giftCards.giftCardNumber

string

Gift card number

Example:

"453456765"

data.cartons.items.giftCards.giftCardStatus

enum<string>

Gift card status

Available options:

PENDING_ACTIVATION,

ACTIVE,

FAILED

Example:

"ACTIVE"

data.cartons.items.itemId

integer

Unique item identifier

Example:

100023

data.cartons.items.lineItemId

string

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"

data.cartons.items.orderId

string

24-character order ID generated in the response of Create Order endpoint - POST /orders

Example:

"6413e370cb0dc859b6c0dcb0"

data.cartons.items.orderNumber

string

Merchant-defined order identifier

Example:

"309020213"

data.cartons.items.orderedQuantity

integer

default:

0

Ordered quantity of given item

Example:

2

data.cartons.items.refundAmount

number

Refund amount for returned items

Example:

10

data.cartons.items.returnQuantity

integer

default:

0

Returned quantity of given item

Example:

1

data.cartons.items.segment

string

Item segment

Example:

"segment"

data.cartons.items.shipmentLineItemId

string

Unique number assigned by merchant to identify item in a shipment. When this value isn't provided, fabric will auto generate it (UUID format) during shipment.

Example:

"607f1f77bcf86cd799439011"

data.cartons.items.shippedQuantity

integer

default:

0

Shipped quantity of given item

Example:

2

data.cartons.items.sku

string

Stock keeping unit (SKU), unique item identifier

Example:

"SKU0023"

data.cartons.items.uom

string

Unit in which a product is measured or sold. UOM can be set to 'each' (EA) or GAL (Gallon), DZ (Dozen), etc.

Example:

"EA"

data.cartons.items.vendorId

string

Vendor ID. Applicable in dropshipping scenarios to indicate the vendor responsible for the given item.

Example:

"vend12346667"

data.cartons.promisedDeliveryDate

string

Promised delivery date given by seller (UTC)

Example:

"2023-03-26T07:58:30.996Z"

data.cartons.shipmentCarrier

string

Shipment carrier name

Example:

"FEDEX"

data.cartons.shipmentMethod

string

Shipment method

Example:

"ground"

data.cartons.tracking

object[]

Carton tracking details

Shipment tracking details

Show child attributes

data.cartons.tracking.event

string

Shipment-specific event. Mandatory in the request body of Update shipment tracking - POST /shipments/actions/update-tracking endpoint

Example:

"picked up"

data.cartons.tracking.eventId

string

Event ID provided by carrier

Example:

"627963716b19511e8a3a631b"

data.cartons.tracking.eventRecordedAt

string

Time event was recorded (UTC)

Example:

"2019-09-30T07:58:30.996Z"

data.cartons.tracking.location

string

Delivery location

Example:

"Reno, NV"

data.cartons.tracking.notes

object

Attributes to save any additional info

Show child attributes

data.cartons.tracking.notes.{key}

string

Attributes to save any additional info

Example:

"{\"description\":\"Shipment picked up\"}"

Example:

{ "description": "Shipment picked up" }

data.cartons.tracking.shipmentCarrier

string

Shipment carrier

Example:

"FEDEX"

data.cartons.trackingNumber

string

Carton tracking number. There is a single tracking number per carton

Example:

"1Z999AA10123456784"

data.cartons.trackingURL

string

Carton tracking URL

Example:

"https://example.com/tracking"

data.cartons.weight

string

Carton weight

Example:

"500 grams"

data.createdAt

string

Shipment creation time (UTC)

Example:

"2023-04-06T07:58:30.996Z"

data.invoiceId

string

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"

data.locationNumber

string

Unique value to identify ship-from location. This must be the locationNumber stored in the fabric Location service.

Example:

"132412"

data.locationType

string

Location type, such as distribution center (DC) or warehouse

Example:

"DC"

data.masterTrackingNumber

string

Master tracking number for all cartons in the shipment

Example:

"TX112345678"

data.orderNumbers

string[]

List of order numbers associated with a shipment. Note: Currently, a shipment can be associated with only one order. In the future, this property will support a scenario where a customer places a second order for the same product immediately after their first order. Multiple order numbers can be linked to one shipment in such cases.

data.poNumber

string

Merchant-defined purchase order number

Example:

"1125"

data.recipients

object[]

Recipient details

Shipment recipient details

Show child attributes

data.recipients.email

string

Recipient's email

Example:

"[e-mail]"

data.recipients.name

object

Contact person's name

Show child attributes

data.recipients.name.firstName

string

Contact person's first name

Example:

"Alex"

data.recipients.name.lastName

string

Contact person's last name

Example:

"Doe"

data.recipients.name.middleName

string

Contact person's middle name or initial

Example:

"E"

data.recipients.phone

object

Contact person's phone details

Show child attributes

data.recipients.phone.number

string

Contact person's phone number

Example:

"123-456-7890"

data.recipients.phone.type

enum<string>

Contact number type

Available options:

MOBILE,

HOME,

BUSINESS

Example:

"MOBILE"

data.reshipmentReasonCode

string

The reshipment reason code.

Example:

"Order is missing"

data.scratchedItems

object[]

Details of scratched items

Customer may cancel allocation line items as part of the shipment post request. In fabric Shipments service, this is called 'Scratched Items' or 'scratchedItems'.

Show child attributes

data.scratchedItems.reasonCode

string

required

Reason code for scratch

Example:

"ReasonCode23454"

data.scratchedItems.itemId

integer

Unique item identifier

Example:

100043

data.scratchedItems.lineItemId

string

Unique number assigned by merchant to identify each item in an order. When this value isn't provided, fabric will auto generate it (in UUID format) during order creation.

Example:

"2"

data.scratchedItems.orderId

string

24-character ID displayed in the response of Create Order endpoint - POST /orders

Example:

"6413e370cb0dc859b6c0dcb0"

data.scratchedItems.quantity

integer

default:

0

Number of scratched items

Example:

1

data.scratchedItems.sku

string

Stock keeping unit (SKU), unique item identifier

Example:

"SKU00043"

data.scratchedItems.subReasonCode

string

Sub-reason code

Example:

"SubReasonCode23242"

data.scratchedItems.uom

string

Unit in which a product is measured or sold. UOM can be set to 'each' (EA) or GAL (Gallon), DZ (Dozen), etc.

Example:

"EA"

data.shipToAddress

object

Address details

Show child attributes

data.shipToAddress.addressLine1

string

required

Address line 1

Example:

"123 Main St."

data.shipToAddress.city

string

required

City name

Example:

"Seattle"

data.shipToAddress.countryCode

string

required

ISO 3166-1 alpha-2 based country code

Example:

"US"

data.shipToAddress.latitude

number

required

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

data.shipToAddress.longitude

number

required

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

data.shipToAddress.postalCode

string

required

Postal or ZIP code

Example:

"98121"

data.shipToAddress.region

string

required

Region or state

Example:

"WA"

data.shipToAddress.type

string

required

Address type

Example:

"Home"

data.shipToAddress.addressLine2

string

Address line 2

Example:

"Suite 100"

data.shipToAddress.addressLine3

string

Address line 3

Example:

"Seventh floor"

data.shipToAddress.addressLine4

string

Address line 4

Example:

"Attention: Pat E. Kake"

data.shipToAddress.email

string

Contact person's email

Example:

"[e-mail]"

data.shipToAddress.name

object

Contact person's name

Show child attributes

data.shipToAddress.name.firstName

string

Contact person's first name

Example:

"Alex"

data.shipToAddress.name.lastName

string

Contact person's last name

Example:

"Doe"

data.shipToAddress.name.middleName

string

Contact person's middle name or initial

Example:

"E"

data.shipToAddress.phone

object

Contact person's phone details

Show child attributes

data.shipToAddress.phone.number

string

Contact person's phone number

Example:

"123-456-7890"

data.shipToAddress.phone.type

enum<string>

Contact number type

Available options:

MOBILE,

HOME,

BUSINESS

Example:

"MOBILE"

data.shipToId

string

Ship-to ID generated in the response of Create shipping endpoint of Shipping service

Example:

"1"

data.shipmentId

string

System-generated shipment ID (UUID)

Example:

"627963716b19511e8a3a631b"

data.shipmentNumber

string

Merchant-defined unique shipment identifier. Note: It can be optionally generated by fabric by using resource generator feature in the Configuration service

Example:

"78974156816152"

data.shippedAt

string

Order shipment time (UTC)

Example:

"2023-04-06T07:58:30.996Z"

data.statusCode

enum<string>

Current shipment status (fabric-defined codes). Note: For standard shipments, the 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

Available options:

SHIPMENT_CREATED,

SHIPMENT_UPDATED,

SHIPMENT_CANCELLED,

PICKUP_CREATED,

PICKUP_COMPLETED,

SHIPMENT_DELIVERED,

SHIPMENT_RETURN_PENDING,

SHIPMENT_RETURN_RECEIVED,

SHIPMENT_PARTIALLY_DELIVERED

Example:

"SHIPMENT_CREATED"

data.subtype

string

Shipment subtype, for another layer of classification. There are no pre-defined values; the possible value is Cash On Delivery (COD)

Example:

"COD"

data.totalCartons

integer

Total number of cartons in the given shipment. There can be only one carton per trackingNumber.

Example:

2

data.type

enum<string>

Shipment types

Available options:

STANDARD,

RESHIP,

RETURN,

SCRATCH,

PENDING_RETURN,

PICKUP,

TRANSFER

Example:

"STANDARD"

data.updatedAt

string

Time of last update to shipment (UTC)

Example:

"2023-04-06T07:58:30.996Z"

data.vendorId

string

Vendor ID. Applicable in dropshipping scenarios to indicate the vendor responsible for the given item.

Example:

"56"

pagination

object

Pagination response

Show child attributes

pagination.count

integer

Total number of search results

Example:

1000

pagination.limit

integer

default:

10

Maximum number of records per page.

Required range: 1 <= x <= 100

Example:

10

pagination.offset

integer

default:

0

The number of records to skip before returning all records. For example, offset=20, limit=10 returns records 21-30.

Required range: x >= 0

Example:

1