Skip to main content

Shipment

All Shipment objects are associated with a specific Workspace, that is why workspace is present in all shipments, and it is required during creation.

The trackingNumber is required for the tracking. Each shipment supports a single tracking number. If you need to use multiple tracking numbers, then you should create separate shipments.

A Shipment created with a valid trackingNumber will automatically populate its tracking information.

Tracking information (origin carrier, destination carrier, tracking status, etc.) is generated by TrackMage and cannot be modified by the user.

Address and shipmentStatus contained within a Shipment may be created at the same time.

What you can do with Shipment#

ShipmentItem Properties#

trackingNumber

Type: string|null

A tracking number, provided by the shipping company.

Example: TM123456789TM

trackingStatus

Type: string|null

The code of the shipment's current tracking status.

Example: in_transit

  • pre_transit - Carrier has received information about the package, but it has not yet been scanned and picked up.
  • no_info - A shipping label has been created, but the package has not yet been scanned and/or picked up by the carrier.
  • in_transit - A package is travelling to its destination. You may receive multiple updates of this type as the package travels to its destination.
  • delivery_in_progress - A package has reached the local area and is in the process of being delivered.
  • delivered - The package has been delivered
  • unsuccessful_delivery - Carrier attempted to deliver, but failed, and usually leaves a notice and will try to deliver again.
  • error - Customs hold or any shipping exceptions. Please contact the carrier.
  • expired - A package has no tracking information for 30 days since it was created.
  • available_for_pickup - The package is available for pickup from the carrier's facility.
  • cancelled - The delivery has been cancelled.
  • return_to_sender - The package was not delivered and is now on its way back to the sender.
  • transit_limit_exceeded - The package has been in transit way longer than normal transit time allows. Please contact the carrier.

orderNumbers

Type: array

List of order numbers to which the shipment belongs.

Example: ['ON1', 'ON2']

email

Type: string|null

Customer email address.

Example: non-existing@trackmage.com

phoneNumber

Type: string|null

Customer phone number.

Example: 13125551212

daysInTransit

Type: integer|null

The number of days from the moment of sending to receiving of the parcel. The "Days in Transit" is the number of days from which the parcel transitioned into an active in-transit status. So once a parcel reaches end status or finite status, something like delivered or canceled or error or other finite states or return back to the sender (that is also finite state) then the days in transit calculation is no longer applied. So we're calculating the days when the parcel actually in transit. That's exactly what it is.

Example: 3

daysInIdle

Type: integer|null

This field is calculated based on idle statuses or the statuses when the shipment actually was created, but it doesn't have a tracking number. So this is a pre-shipment state, or pre-transit state, no info state, whenever we are actually ordering the parcels from a supplier and we don't have confirmation from their end or the tracking number for the parcel. Once the parcel transitions to an in-transit state or other active statuses or any finite statuses, then the "days in idle" counter stops to be calculated.

Example: 10

originCarrier

Type: string|null

The code of origin carrier. Origin Carrier will be identified automatically based on Tracking Number. Sometimes the carrier cannot be identified. In that case, the system will return the error with the suggested carriers list in the payload. The value of this field can be specified only once in POST request.

Example: china-post

destinationCarrier

Type: string|null

The code of destination carrier.

Example: dhl

originCountry

Type: string|null

The origin country name.

Example: China

destinationCountry

Type: string|null

The destination country name.

Example: Poland

originCountryIso2

Type: string|null

The two-letter country code corresponding to the origin country.

Example: CN

destinationCountryIso2

Type: string|null

The two-letter country code corresponding to the destination country.

Example: PL

shippedAt

Type: string|null (format: date-time)

Shipment dispatch date (in ISO-8601 format).

Example: 1610236800

expectedDeliveryDate

Type: string|null (format: date-time)

Shipment expected delivery date (in ISO-8601 format).

Example: 1610236800

createdAt

Type: string (format: date-time)

The date and time (in ISO-8601 format) when the shipment was created.

Example: 1610236800

updatedAt

Type: string (format: date-time)

The date and time (in ISO-8601 format) when the shipment was updated.

Example: 1610236800

lastStatusUpdate

Type: string|null (format: date-time)

The date and time (in ISO-8601 format) when the tracking status was updated.

Example: 1610236800

workspace
REQUIRED

Type: string (format: iri-reference)

The workspace reference to which the shipment belongs.

Example: /workspaces/cbe5589f-8869-4a9c-9d9c-3d7f70d66878

review

Type: string|null (format: iri-reference)

reviewTotalScore

Type: number|null

orders

Type: array

List of order references to which the shipment belongs.

Example: ['/orders/cbe5589f-8869-4a9c-9d9c-3d7f70d66878']

shipmentItems

Type: array

List of shipment items references that belong to the shipment.

Example: [ '/shipment_items/cbe5589f-8869-4a9c-9d9c-3d7f70d66878', '/shipment_items/3eb2f084-ea29-41ed-9bfb-691381bd7511' ]

externalSourceIntegration

Type: string|null (format: iri-reference)

The workflow reference to integration for ecommerce store.

Example: /workflows/a0b97939-5aea-4b35-b7c6-64f56bff1721

externalSourceSyncId

Type: string|null

The id of the shipment in ecommerce store (WooCommerce, Shopify, etc.).

Example: ws_123456

fulfillmentIntegration

Type: string|null (format: iri-reference)

The workflow reference to integration for fulfillment source.

Example: /workflows/x5b97939-5aea-4b35-b7c6-64f56bff1722

fulfillmentSyncId

Type: string|null

The id of the shipment in the fulfillment source system (AliExpress, Amazon, etc.).

Example: als_123456

address

Type: object|null

The mailing address to where the order will be shipped. Represented by the Address object.

Example:
"address": {
  "addressLine1": "567 East Cedar",
  "addressLine2": "Apartment 1",
  "city": "Liberal",
  "company": "Acme, Inc.",
  "country": "United States",
  "countryIso2": "US",
  "firstName": "Dorothy",
  "lastName": "Gale",
  "postcode": 67901,
  "state": "Kansas"
}
  • addressLine1:

    The street address. This field is optional.

  • addressLine2:

    An optional additional field for the street address. This field is optional.

  • city:

    The city, town, or village. This field is optional.

  • company:

    The company of the person associated with the address. This field is optional.

  • country:

    The name of the country. This field is optional.

  • countryIso2:

    The two-letter country code. This field is optional.

  • firstName:

    The first name of the person associated with the address. This field is optional.

  • lastName:

    The last name of the person associated with the address. This field is optional.

  • postcode:

    The postal code (zip, postcode, Eircode, …). This field is optional.

  • state:

    The name of the region (province, state, prefecture, …). This field is optional.

shipmentStatus

Type: object|null

The current status of shipment. Represented by the Status object.

Example:
"shipmentStatus": {
  "code": "new",
  "title": "New",
  "id": "c2dc66dc-9b21-4144-8b1f-4e1e1bb866d6"
}
  • code:

    A unique status code. This field is required.

  • title:

    A status name. This field is optional.

  • id:

    A version 4 UUID.

id
READ-ONLY

Type: string (format: uuid)

A version 4 UUID.

Example: 83829499-f99c-4c91-9908-76c91f2ae312

Endpoints#

GET
/shipments
Retrieves the collection of Shipment resources.
Query Parameters
NameInIs RequiredTypeDescription
order[id]queryNostring
Allowed values: asc|desc
order[trackingNumber]queryNostring
Allowed values: asc|desc
order[trackingStatus]queryNostring
Allowed values: asc|desc
order[shipmentStatus.code]queryNostring
Allowed values: asc|desc
order[originCarrier]queryNostring
Allowed values: asc|desc
order[destinationCarrier]queryNostring
Allowed values: asc|desc
order[createdAt]queryNostring
Allowed values: asc|desc
order[updatedAt]queryNostring
Allowed values: asc|desc
order[shippedAt]queryNostring
Allowed values: asc|desc
order[lastStatusUpdate]queryNostring
Allowed values: asc|desc
order[expectedDeliveryDate]queryNostring
Allowed values: asc|desc
order[originCountry]queryNostring
Allowed values: asc|desc
order[destinationCountry]queryNostring
Allowed values: asc|desc
order[originCountryIso2]queryNostring
Allowed values: asc|desc
order[destinationCountryIso2]queryNostring
Allowed values: asc|desc
order[email]queryNostring
Allowed values: asc|desc
order[phoneNumber]queryNostring
Allowed values: asc|desc
order[daysInTransit]queryNostring
Allowed values: asc|desc
order[reviewTotalScore]queryNostring
Allowed values: asc|desc
order[address.addressLine1]queryNostring
Allowed values: asc|desc
order[address.addressLine2]queryNostring
Allowed values: asc|desc
order[address.city]queryNostring
Allowed values: asc|desc
order[address.company]queryNostring
Allowed values: asc|desc
order[address.countryIso2]queryNostring
Allowed values: asc|desc
order[address.firstName]queryNostring
Allowed values: asc|desc
order[address.lastName]queryNostring
Allowed values: asc|desc
order[address.postcode]queryNostring
Allowed values: asc|desc
order[address.state]queryNostring
Allowed values: asc|desc
orderNumbersqueryNostring
orderNumbers[]queryNoarray
Array of Strings.
createdAt[before]queryNostring
createdAt[strictly_before]queryNostring
createdAt[after]queryNostring
createdAt[strictly_after]queryNostring
updatedAt[before]queryNostring
updatedAt[strictly_before]queryNostring
updatedAt[after]queryNostring
updatedAt[strictly_after]queryNostring
shippedAt[before]queryNostring
shippedAt[strictly_before]queryNostring
shippedAt[after]queryNostring
shippedAt[strictly_after]queryNostring
lastStatusUpdate[before]queryNostring
lastStatusUpdate[strictly_before]queryNostring
lastStatusUpdate[after]queryNostring
lastStatusUpdate[strictly_after]queryNostring
expectedDeliveryDate[before]queryNostring
expectedDeliveryDate[strictly_before]queryNostring
expectedDeliveryDate[after]queryNostring
expectedDeliveryDate[strictly_after]queryNostring
idqueryNostring
id[]queryNoarray
Array of Strings.
trackingNumberqueryNostring
trackingStatusqueryNostring
trackingStatus[]queryNoarray
Array of Strings.
shipmentStatus.codequeryNostring
shipmentStatus.code[]queryNoarray
Array of Strings.
originCarrierqueryNostring
originCarrier[]queryNoarray
Array of Strings.
destinationCarrierqueryNostring
destinationCarrier[]queryNoarray
Array of Strings.
originCountryqueryNostring
originCountryIso2queryNostring
originCountryIso2[]queryNoarray
Array of Strings.
destinationCountryqueryNostring
destinationCountryIso2queryNostring
destinationCountryIso2[]queryNoarray
Array of Strings.
emailqueryNostring
phoneNumberqueryNostring
address.addressLine1queryNostring
address.addressLine2queryNostring
address.cityqueryNostring
address.companyqueryNostring
address.countryIso2queryNostring
address.countryIso2[]queryNoarray
Array of Strings.
address.firstNamequeryNostring
address.lastNamequeryNostring
address.postcodequeryNostring
address.statequeryNostring
daysInTransitqueryNointeger
daysInTransit[]queryNoarray
Array of Integers.
daysInTransit[between]queryNostring
daysInTransit[gt]queryNostring
daysInTransit[gte]queryNostring
daysInTransit[lt]queryNostring
daysInTransit[lte]queryNostring
reviewTotalScore[between]queryNostring
reviewTotalScore[gt]queryNostring
reviewTotalScore[gte]queryNostring
reviewTotalScore[lt]queryNostring
reviewTotalScore[lte]queryNostring
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/shipments/{id}
Retrieves a Shipment resource.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
GET
/workspaces/{id}/shipments
Retrieves the collection of Shipment resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
order[id]queryNostring
Allowed values: asc|desc
order[trackingNumber]queryNostring
Allowed values: asc|desc
order[trackingStatus]queryNostring
Allowed values: asc|desc
order[shipmentStatus.code]queryNostring
Allowed values: asc|desc
order[originCarrier]queryNostring
Allowed values: asc|desc
order[destinationCarrier]queryNostring
Allowed values: asc|desc
order[createdAt]queryNostring
Allowed values: asc|desc
order[updatedAt]queryNostring
Allowed values: asc|desc
order[shippedAt]queryNostring
Allowed values: asc|desc
order[lastStatusUpdate]queryNostring
Allowed values: asc|desc
order[expectedDeliveryDate]queryNostring
Allowed values: asc|desc
order[originCountry]queryNostring
Allowed values: asc|desc
order[destinationCountry]queryNostring
Allowed values: asc|desc
order[originCountryIso2]queryNostring
Allowed values: asc|desc
order[destinationCountryIso2]queryNostring
Allowed values: asc|desc
order[email]queryNostring
Allowed values: asc|desc
order[phoneNumber]queryNostring
Allowed values: asc|desc
order[daysInTransit]queryNostring
Allowed values: asc|desc
order[reviewTotalScore]queryNostring
Allowed values: asc|desc
order[address.addressLine1]queryNostring
Allowed values: asc|desc
order[address.addressLine2]queryNostring
Allowed values: asc|desc
order[address.city]queryNostring
Allowed values: asc|desc
order[address.company]queryNostring
Allowed values: asc|desc
order[address.countryIso2]queryNostring
Allowed values: asc|desc
order[address.firstName]queryNostring
Allowed values: asc|desc
order[address.lastName]queryNostring
Allowed values: asc|desc
order[address.postcode]queryNostring
Allowed values: asc|desc
order[address.state]queryNostring
Allowed values: asc|desc
orderNumbersqueryNostring
orderNumbers[]queryNoarray
Array of Strings.
createdAt[before]queryNostring
createdAt[strictly_before]queryNostring
createdAt[after]queryNostring
createdAt[strictly_after]queryNostring
updatedAt[before]queryNostring
updatedAt[strictly_before]queryNostring
updatedAt[after]queryNostring
updatedAt[strictly_after]queryNostring
shippedAt[before]queryNostring
shippedAt[strictly_before]queryNostring
shippedAt[after]queryNostring
shippedAt[strictly_after]queryNostring
lastStatusUpdate[before]queryNostring
lastStatusUpdate[strictly_before]queryNostring
lastStatusUpdate[after]queryNostring
lastStatusUpdate[strictly_after]queryNostring
expectedDeliveryDate[before]queryNostring
expectedDeliveryDate[strictly_before]queryNostring
expectedDeliveryDate[after]queryNostring
expectedDeliveryDate[strictly_after]queryNostring
id[]queryNoarray
Array of Strings.
trackingNumberqueryNostring
trackingStatusqueryNostring
trackingStatus[]queryNoarray
Array of Strings.
shipmentStatus.codequeryNostring
shipmentStatus.code[]queryNoarray
Array of Strings.
originCarrierqueryNostring
originCarrier[]queryNoarray
Array of Strings.
destinationCarrierqueryNostring
destinationCarrier[]queryNoarray
Array of Strings.
originCountryqueryNostring
originCountryIso2queryNostring
originCountryIso2[]queryNoarray
Array of Strings.
destinationCountryqueryNostring
destinationCountryIso2queryNostring
destinationCountryIso2[]queryNoarray
Array of Strings.
emailqueryNostring
phoneNumberqueryNostring
address.addressLine1queryNostring
address.addressLine2queryNostring
address.cityqueryNostring
address.companyqueryNostring
address.countryIso2queryNostring
address.countryIso2[]queryNoarray
Array of Strings.
address.firstNamequeryNostring
address.lastNamequeryNostring
address.postcodequeryNostring
address.statequeryNostring
daysInTransitqueryNointeger
daysInTransit[]queryNoarray
Array of Integers.
daysInTransit[between]queryNostring
daysInTransit[gt]queryNostring
daysInTransit[gte]queryNostring
daysInTransit[lt]queryNostring
daysInTransit[lte]queryNostring
reviewTotalScore[between]queryNostring
reviewTotalScore[gt]queryNostring
reviewTotalScore[gte]queryNostring
reviewTotalScore[lt]queryNostring
reviewTotalScore[lte]queryNostring
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/shipments/{id}/checkpoints
Retrieves the collection of TrackingCheckpoint resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
order[checkpointDate]queryNostring
Allowed values: asc|desc
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/shipments/{id}/shipment_items
Retrieves the collection of ShipmentItem resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
id[]queryNoarray
Array of Strings.
shipment.idqueryNostring
shipment.id[]queryNoarray
Array of Strings.
shipment.trackingNumberqueryNostring
orderItem.idqueryNostring
orderItem.id[]queryNoarray
Array of Strings.
orderItem.order.idqueryNostring
orderItem.order.id[]queryNoarray
Array of Strings.
workspace.idqueryNostring
workspace.id[]queryNoarray
Array of Strings.
order[id]queryNostring
Allowed values: asc|desc
order[qty]queryNostring
Allowed values: asc|desc
qtyqueryNointeger
qty[]queryNoarray
Array of Integers.
qty[between]queryNostring
qty[gt]queryNostring
qty[gte]queryNostring
qty[lt]queryNostring
qty[lte]queryNostring
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/teams/{id}/workspaces/{workspaces}/shipments
Retrieves the collection of Shipment resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
workspacespathYesstring
order[id]queryNostring
Allowed values: asc|desc
order[trackingNumber]queryNostring
Allowed values: asc|desc
order[trackingStatus]queryNostring
Allowed values: asc|desc
order[shipmentStatus.code]queryNostring
Allowed values: asc|desc
order[originCarrier]queryNostring
Allowed values: asc|desc
order[destinationCarrier]queryNostring
Allowed values: asc|desc
order[createdAt]queryNostring
Allowed values: asc|desc
order[updatedAt]queryNostring
Allowed values: asc|desc
order[shippedAt]queryNostring
Allowed values: asc|desc
order[lastStatusUpdate]queryNostring
Allowed values: asc|desc
order[expectedDeliveryDate]queryNostring
Allowed values: asc|desc
order[originCountry]queryNostring
Allowed values: asc|desc
order[destinationCountry]queryNostring
Allowed values: asc|desc
order[originCountryIso2]queryNostring
Allowed values: asc|desc
order[destinationCountryIso2]queryNostring
Allowed values: asc|desc
order[email]queryNostring
Allowed values: asc|desc
order[phoneNumber]queryNostring
Allowed values: asc|desc
order[daysInTransit]queryNostring
Allowed values: asc|desc
order[reviewTotalScore]queryNostring
Allowed values: asc|desc
order[address.addressLine1]queryNostring
Allowed values: asc|desc
order[address.addressLine2]queryNostring
Allowed values: asc|desc
order[address.city]queryNostring
Allowed values: asc|desc
order[address.company]queryNostring
Allowed values: asc|desc
order[address.countryIso2]queryNostring
Allowed values: asc|desc
order[address.firstName]queryNostring
Allowed values: asc|desc
order[address.lastName]queryNostring
Allowed values: asc|desc
order[address.postcode]queryNostring
Allowed values: asc|desc
order[address.state]queryNostring
Allowed values: asc|desc
orderNumbersqueryNostring
orderNumbers[]queryNoarray
Array of Strings.
createdAt[before]queryNostring
createdAt[strictly_before]queryNostring
createdAt[after]queryNostring
createdAt[strictly_after]queryNostring
updatedAt[before]queryNostring
updatedAt[strictly_before]queryNostring
updatedAt[after]queryNostring
updatedAt[strictly_after]queryNostring
shippedAt[before]queryNostring
shippedAt[strictly_before]queryNostring
shippedAt[after]queryNostring
shippedAt[strictly_after]queryNostring
lastStatusUpdate[before]queryNostring
lastStatusUpdate[strictly_before]queryNostring
lastStatusUpdate[after]queryNostring
lastStatusUpdate[strictly_after]queryNostring
expectedDeliveryDate[before]queryNostring
expectedDeliveryDate[strictly_before]queryNostring
expectedDeliveryDate[after]queryNostring
expectedDeliveryDate[strictly_after]queryNostring
id[]queryNoarray
Array of Strings.
trackingNumberqueryNostring
trackingStatusqueryNostring
trackingStatus[]queryNoarray
Array of Strings.
shipmentStatus.codequeryNostring
shipmentStatus.code[]queryNoarray
Array of Strings.
originCarrierqueryNostring
originCarrier[]queryNoarray
Array of Strings.
destinationCarrierqueryNostring
destinationCarrier[]queryNoarray
Array of Strings.
originCountryqueryNostring
originCountryIso2queryNostring
originCountryIso2[]queryNoarray
Array of Strings.
destinationCountryqueryNostring
destinationCountryIso2queryNostring
destinationCountryIso2[]queryNoarray
Array of Strings.
emailqueryNostring
phoneNumberqueryNostring
address.addressLine1queryNostring
address.addressLine2queryNostring
address.cityqueryNostring
address.companyqueryNostring
address.countryIso2queryNostring
address.countryIso2[]queryNoarray
Array of Strings.
address.firstNamequeryNostring
address.lastNamequeryNostring
address.postcodequeryNostring
address.statequeryNostring
daysInTransitqueryNointeger
daysInTransit[]queryNoarray
Array of Integers.
daysInTransit[between]queryNostring
daysInTransit[gt]queryNostring
daysInTransit[gte]queryNostring
daysInTransit[lt]queryNostring
daysInTransit[lte]queryNostring
reviewTotalScore[between]queryNostring
reviewTotalScore[gt]queryNostring
reviewTotalScore[gte]queryNostring
reviewTotalScore[lt]queryNostring
reviewTotalScore[lte]queryNostring
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/workspaces/{id}/shipments/{shipments}/checkpoints
Retrieves the collection of TrackingCheckpoint resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
shipmentspathYesstring
order[checkpointDate]queryNostring
Allowed values: asc|desc
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/workspaces/{id}/shipments/{shipments}/shipment_items
Retrieves the collection of ShipmentItem resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
shipmentspathYesstring
id[]queryNoarray
Array of Strings.
shipment.idqueryNostring
shipment.id[]queryNoarray
Array of Strings.
shipment.trackingNumberqueryNostring
orderItem.idqueryNostring
orderItem.id[]queryNoarray
Array of Strings.
orderItem.order.idqueryNostring
orderItem.order.id[]queryNoarray
Array of Strings.
workspace.idqueryNostring
workspace.id[]queryNoarray
Array of Strings.
order[id]queryNostring
Allowed values: asc|desc
order[qty]queryNostring
Allowed values: asc|desc
qtyqueryNointeger
qty[]queryNoarray
Array of Integers.
qty[between]queryNostring
qty[gt]queryNostring
qty[gte]queryNostring
qty[lt]queryNostring
qty[lte]queryNostring
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/teams/{id}/workspaces/{workspaces}/shipments/{shipments}/checkpoints
Retrieves the collection of TrackingCheckpoint resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
workspacespathYesstring
shipmentspathYesstring
order[checkpointDate]queryNostring
Allowed values: asc|desc
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
GET
/teams/{id}/workspaces/{workspaces}/shipments/{shipments}/shipment_items
Retrieves the collection of ShipmentItem resources.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
workspacespathYesstring
shipmentspathYesstring
id[]queryNoarray
Array of Strings.
shipment.idqueryNostring
shipment.id[]queryNoarray
Array of Strings.
shipment.trackingNumberqueryNostring
orderItem.idqueryNostring
orderItem.id[]queryNoarray
Array of Strings.
orderItem.order.idqueryNostring
orderItem.order.id[]queryNoarray
Array of Strings.
workspace.idqueryNostring
workspace.id[]queryNoarray
Array of Strings.
order[id]queryNostring
Allowed values: asc|desc
order[qty]queryNostring
Allowed values: asc|desc
qtyqueryNointeger
qty[]queryNoarray
Array of Integers.
qty[between]queryNostring
qty[gt]queryNostring
qty[gte]queryNostring
qty[lt]queryNostring
qty[lte]queryNostring
pagequeryNointegerThe collection page number
The default value: 1
itemsPerPagequeryNointegerThe number of items per page
The default value: 30
The minimal value: 0
POST
/shipments
Creates a Shipment resource.
Request Body Parameters

trackingNumber

Type: string|null

A tracking number, provided by the shipping company.

Example: TM123456789TM

orderNumbers

Type: array

List of order numbers to which the shipment belongs.

Example: ['ON1', 'ON2']

email

Type: string|null

Customer email address.

Example: non-existing@trackmage.com

phoneNumber

Type: string|null

Customer phone number.

Example: 13125551212

originCarrier

Type: string|null

The code of origin carrier. Origin Carrier will be identified automatically based on Tracking Number. Sometimes the carrier cannot be identified. In that case, the system will return the error with the suggested carriers list in the payload. The value of this field can be specified only once in POST request.

Example: china-post

workspace
REQUIRED

Type: string (format: iri-reference)

The workspace reference to which the shipment belongs.

Example: /workspaces/cbe5589f-8869-4a9c-9d9c-3d7f70d66878

orders

Type: array

List of order references to which the shipment belongs.

Example: ['/orders/cbe5589f-8869-4a9c-9d9c-3d7f70d66878']

shipmentItems

Type: array

List of shipment items references that belong to the shipment.

Example: [ '/shipment_items/cbe5589f-8869-4a9c-9d9c-3d7f70d66878', '/shipment_items/3eb2f084-ea29-41ed-9bfb-691381bd7511' ]

externalSourceIntegration

Type: string|null (format: iri-reference)

The workflow reference to integration for ecommerce store.

Example: /workflows/a0b97939-5aea-4b35-b7c6-64f56bff1721

externalSourceSyncId

Type: string|null

The id of the shipment in ecommerce store (WooCommerce, Shopify, etc.).

Example: ws_123456

fulfillmentIntegration

Type: string|null (format: iri-reference)

The workflow reference to integration for fulfillment source.

Example: /workflows/x5b97939-5aea-4b35-b7c6-64f56bff1722

fulfillmentSyncId

Type: string|null

The id of the shipment in the fulfillment source system (AliExpress, Amazon, etc.).

Example: als_123456

address

Type: object|null

The mailing address to where the order will be shipped. Represented by the Address object.

Example:
"address": {
  "addressLine1": "567 East Cedar",
  "addressLine2": "Apartment 1",
  "city": "Liberal",
  "company": "Acme, Inc.",
  "country": "United States",
  "countryIso2": "US",
  "firstName": "Dorothy",
  "lastName": "Gale",
  "postcode": 67901,
  "state": "Kansas"
}
  • addressLine1:

    The street address. This field is optional.

  • addressLine2:

    An optional additional field for the street address. This field is optional.

  • city:

    The city, town, or village. This field is optional.

  • company:

    The company of the person associated with the address. This field is optional.

  • country:

    The name of the country. This field is optional.

  • countryIso2:

    The two-letter country code. This field is optional.

  • firstName:

    The first name of the person associated with the address. This field is optional.

  • lastName:

    The last name of the person associated with the address. This field is optional.

  • postcode:

    The postal code (zip, postcode, Eircode, …). This field is optional.

  • state:

    The name of the region (province, state, prefecture, …). This field is optional.

shipmentStatus

Type: object|null

The current status of shipment. Represented by the Status object.

Example:
"shipmentStatus": {
  "code": "new",
  "title": "New"
}
  • code:

    A unique status code. This field is required.

  • title:

    A status name. This field is optional.

PUT
/shipments/{id}
Replaces the Shipment resource.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring
Request Body Parameters

trackingNumber

Type: string|null

A tracking number, provided by the shipping company.

Example: TM123456789TM

orderNumbers

Type: array

List of order numbers to which the shipment belongs.

Example: ['ON1', 'ON2']

email

Type: string|null

Customer email address.

Example: non-existing@trackmage.com

phoneNumber

Type: string|null

Customer phone number.

Example: 13125551212

originCarrier

Type: string|null

The code of origin carrier. Origin Carrier will be identified automatically based on Tracking Number. Sometimes the carrier cannot be identified. In that case, the system will return the error with the suggested carriers list in the payload. The value of this field can be specified only once in POST request.

Example: china-post

orders

Type: array

List of order references to which the shipment belongs.

Example: ['/orders/cbe5589f-8869-4a9c-9d9c-3d7f70d66878']

shipmentItems

Type: array

List of shipment items references that belong to the shipment.

Example: [ '/shipment_items/cbe5589f-8869-4a9c-9d9c-3d7f70d66878', '/shipment_items/3eb2f084-ea29-41ed-9bfb-691381bd7511' ]

address

Type: object|null

The mailing address to where the order will be shipped. Represented by the Address object.

Example:
"address": {
  "addressLine1": "567 East Cedar",
  "addressLine2": "Apartment 1",
  "city": "Liberal",
  "company": "Acme, Inc.",
  "country": "United States",
  "countryIso2": "US",
  "firstName": "Dorothy",
  "lastName": "Gale",
  "postcode": 67901,
  "state": "Kansas"
}
  • addressLine1:

    The street address. This field is optional.

  • addressLine2:

    An optional additional field for the street address. This field is optional.

  • city:

    The city, town, or village. This field is optional.

  • company:

    The company of the person associated with the address. This field is optional.

  • country:

    The name of the country. This field is optional.

  • countryIso2:

    The two-letter country code. This field is optional.

  • firstName:

    The first name of the person associated with the address. This field is optional.

  • lastName:

    The last name of the person associated with the address. This field is optional.

  • postcode:

    The postal code (zip, postcode, Eircode, …). This field is optional.

  • state:

    The name of the region (province, state, prefecture, …). This field is optional.

shipmentStatus

Type: object|null

The current status of shipment. Represented by the Status object.

Example:
"shipmentStatus": {
  "code": "new",
  "title": "New"
}
  • code:

    A unique status code. This field is required.

  • title:

    A status name. This field is optional.

DELETE
/shipments/{id}
Removes the Shipment resource.
Query Parameters
NameInIs RequiredTypeDescription
idpathYesstring