Update shipment tracking

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.

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

Body

application/json

Shipment tracking details

shipmentNumber

string

required

Merchant-defined unique shipment identifier

Example:

"78974156816152"

trackingNumber

string

required

Tracking number

Example:

"1Z999AA10123456784"

tracking

object[]

Tracking details

Shipment tracking details

Show child attributes

tracking.event

string

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

Example:

"picked up"

tracking.eventId

string

Event ID provided by carrier

Example:

"627963716b19511e8a3a631b"

tracking.eventRecordedAt

string

Time event was recorded (UTC)

Example:

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

tracking.location

string

Delivery location

Example:

"Reno, NV"

tracking.notes

object

Attributes to save any additional info

Show child attributes

tracking.notes.{key}

string

Attributes to save any additional info

Example:

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

Example:

{ "description": "Shipment picked up" }

tracking.shipmentCarrier

string

Shipment carrier

Example:

"FEDEX"

trackingURL

string

Tracking URL

Example:

"https://example.com/tracking"

Response

200

application/json

OK

Shipment response

shipments

object[]

Shipment details

Shipment details

Show child attributes

shipments.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

shipments.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"

shipments.auditLogs

object[]

Audit log details

Details for updating shipment

Show child attributes

shipments.auditLogs.auditId

string

System-generated audit ID (UUID format)

Example:

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

shipments.auditLogs.auditType

string

Audit type such as cancel, return, etc.

Example:

"CANCEL"

shipments.auditLogs.auditedAt

string

Audit time (UTC)

Example:

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

shipments.auditLogs.employeeId

string

Employee (ID or name) who made the last update

Example:

"6227"

shipments.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"

shipments.auditLogs.note

string

Additional info, if any

Example:

"Note"

shipments.auditLogs.reasonCode

string

Merchant-defined reason code, varies from merchant to merchant

Example:

"Scratched item"

shipments.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"

shipments.auditLogs.subReasonCode

string

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

Example:

"Scratched item"

shipments.auditLogs.updatedFields

object[]

Audit log for change history

Audit log for change history

Show child attributes

shipments.auditLogs.updatedFields.fieldName

string

Field or property name that was updated

Example:

"UOM"

shipments.auditLogs.updatedFields.fieldOriginalValue

string

Original value of fieldName before it was updated

Example:

"PK"

shipments.cartons

object[]

Carton details

Carton details

Show child attributes

shipments.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"

shipments.cartons.cartonType

string

Carton type

Example:

"Package"

shipments.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"

shipments.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"

shipments.cartons.items

object[]

Carton item details

Details of item in shipment

Show child attributes

shipments.cartons.items.fees

object[]

Fee details

Return fee details

Show child attributes

shipments.cartons.items.fees.amount

number

Merchant-defined return amount

Example:

34.56

shipments.cartons.items.fees.name

string

Fee name

Example:

"RETURN_FEE"

shipments.cartons.items.fees.reason

string

Merchant-defined return reason

Example:

"Return fee"

shipments.cartons.items.fees.type

enum<string>

Return fee type

Available options:

TAX,

DISCOUNT,

FEE,

ITEM,

ADJUSTMENT

Example:

"FEE"

shipments.cartons.items.giftCards

object[]

Gift card details

Gift card details

Show child attributes

shipments.cartons.items.giftCards.amount

number

Gift card amount

Example:

50

shipments.cartons.items.giftCards.giftCardActivatedAt

string

Time gift card was activated (UTC)

Example:

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

shipments.cartons.items.giftCards.giftCardActivationRequestedAt

string

Time of placing gift card activation request (UTC)

Example:

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

shipments.cartons.items.giftCards.giftCardNumber

string

Gift card number

Example:

"453456765"

shipments.cartons.items.giftCards.giftCardStatus

enum<string>

Gift card status

Available options:

PENDING_ACTIVATION,

ACTIVE,

FAILED

Example:

"ACTIVE"

shipments.cartons.items.itemId

integer

Unique item identifier

Example:

100023

shipments.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"

shipments.cartons.items.orderId

string

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

Example:

"6413e370cb0dc859b6c0dcb0"

shipments.cartons.items.orderNumber

string

Merchant-defined order identifier

Example:

"309020213"

shipments.cartons.items.orderedQuantity

integer

default:

0

Ordered quantity of given item

Example:

2

shipments.cartons.items.refundAmount

number

Refund amount for returned items

Example:

10

shipments.cartons.items.returnQuantity

integer

default:

0

Returned quantity of given item

Example:

1

shipments.cartons.items.segment

string

Item segment

Example:

"segment"

shipments.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"

shipments.cartons.items.shippedQuantity

integer

default:

0

Shipped quantity of given item

Example:

2

shipments.cartons.items.sku

string

Stock keeping unit (SKU), unique item identifier

Example:

"SKU0023"

shipments.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"

shipments.cartons.items.vendorId

string

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

Example:

"vend12346667"

shipments.cartons.promisedDeliveryDate

string

Promised delivery date given by seller (UTC)

Example:

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

shipments.cartons.shipmentCarrier

string

Shipment carrier name

Example:

"FEDEX"

shipments.cartons.shipmentMethod

string

Shipment method

Example:

"ground"

shipments.cartons.tracking

object[]

Carton tracking details

Shipment tracking details

Show child attributes

shipments.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"

shipments.cartons.tracking.eventId

string

Event ID provided by carrier

Example:

"627963716b19511e8a3a631b"

shipments.cartons.tracking.eventRecordedAt

string

Time event was recorded (UTC)

Example:

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

shipments.cartons.tracking.location

string

Delivery location

Example:

"Reno, NV"

shipments.cartons.tracking.notes

object

Attributes to save any additional info

Show child attributes

shipments.cartons.tracking.notes.{key}

string

Attributes to save any additional info

Example:

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

Example:

{ "description": "Shipment picked up" }

shipments.cartons.tracking.shipmentCarrier

string

Shipment carrier

Example:

"FEDEX"

shipments.cartons.trackingNumber

string

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

Example:

"1Z999AA10123456784"

shipments.cartons.trackingURL

string

Carton tracking URL

Example:

"https://example.com/tracking"

shipments.cartons.weight

string

Carton weight

Example:

"500 grams"

shipments.createdAt

string

Shipment creation time (UTC)

Example:

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

shipments.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"

shipments.locationNumber

string

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

Example:

"132412"

shipments.locationType

string

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

Example:

"DC"

shipments.masterTrackingNumber

string

Master tracking number for all cartons in the shipment

Example:

"TX112345678"

shipments.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.

shipments.poNumber

string

Merchant-defined purchase order number

Example:

"1125"

shipments.recipients

object[]

Recipient details

Shipment recipient details

Show child attributes

shipments.recipients.email

string

Recipient's email

Example:

"[e-mail]"

shipments.recipients.name

object

Contact person's name

Show child attributes

shipments.recipients.name.firstName

string

Contact person's first name

Example:

"Alex"

shipments.recipients.name.lastName

string

Contact person's last name

Example:

"Doe"

shipments.recipients.name.middleName

string

Contact person's middle name or initial

Example:

"E"

shipments.recipients.phone

object

Contact person's phone details

Show child attributes

shipments.recipients.phone.number

string

Contact person's phone number

Example:

"123-456-7890"

shipments.recipients.phone.type

enum<string>

Contact number type

Available options:

MOBILE,

HOME,

BUSINESS

Example:

"MOBILE"

shipments.reshipmentReasonCode

string

The reshipment reason code.

Example:

"Order is missing"

shipments.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

shipments.scratchedItems.reasonCode

string

required

Reason code for scratch

Example:

"ReasonCode23454"

shipments.scratchedItems.itemId

integer

Unique item identifier

Example:

100043

shipments.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"

shipments.scratchedItems.orderId

string

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

Example:

"6413e370cb0dc859b6c0dcb0"

shipments.scratchedItems.quantity

integer

default:

0

Number of scratched items

Example:

1

shipments.scratchedItems.sku

string

Stock keeping unit (SKU), unique item identifier

Example:

"SKU00043"

shipments.scratchedItems.subReasonCode

string

Sub-reason code

Example:

"SubReasonCode23242"

shipments.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"

shipments.shipToAddress

object

Address details

Show child attributes

shipments.shipToAddress.addressLine1

string

required

Address line 1

Example:

"123 Main St."

shipments.shipToAddress.city

string

required

City name

Example:

"Seattle"

shipments.shipToAddress.countryCode

string

required

ISO 3166-1 alpha-2 based country code

Example:

"US"

shipments.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

shipments.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

shipments.shipToAddress.postalCode

string

required

Postal or ZIP code

Example:

"98121"

shipments.shipToAddress.region

string

required

Region or state

Example:

"WA"

shipments.shipToAddress.type

string

required

Address type

Example:

"Home"

shipments.shipToAddress.addressLine2

string

Address line 2

Example:

"Suite 100"

shipments.shipToAddress.addressLine3

string

Address line 3

Example:

"Seventh floor"

shipments.shipToAddress.addressLine4

string

Address line 4

Example:

"Attention: Pat E. Kake"

shipments.shipToAddress.email

string

Contact person's email

Example:

"[e-mail]"

shipments.shipToAddress.name

object

Contact person's name

Show child attributes

shipments.shipToAddress.name.firstName

string

Contact person's first name

Example:

"Alex"

shipments.shipToAddress.name.lastName

string

Contact person's last name

Example:

"Doe"

shipments.shipToAddress.name.middleName

string

Contact person's middle name or initial

Example:

"E"

shipments.shipToAddress.phone

object

Contact person's phone details

Show child attributes

shipments.shipToAddress.phone.number

string

Contact person's phone number

Example:

"123-456-7890"

shipments.shipToAddress.phone.type

enum<string>

Contact number type

Available options:

MOBILE,

HOME,

BUSINESS

Example:

"MOBILE"

shipments.shipToId

string

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

Example:

"1"

shipments.shipmentId

string

System-generated shipment ID (UUID)

Example:

"627963716b19511e8a3a631b"

shipments.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"

shipments.shippedAt

string

Order shipment time (UTC)

Example:

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

shipments.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"

shipments.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"

shipments.totalCartons

integer

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

Example:

2

shipments.type

enum<string>

Shipment types

Available options:

STANDARD,

RESHIP,

RETURN,

SCRATCH,

PENDING_RETURN,

PICKUP,

TRANSFER

Example:

"STANDARD"

shipments.updatedAt

string

Time of last update to shipment (UTC)

Example:

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

shipments.vendorId

string

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

Example:

"56"