Shipment

Shipments are not created in the system until an order goes into picking. There may be multiple shipments for one order depending on the overall weight and number of items on the order. Although there may be more than one package for a single shipment, most shipments will have only one package. A packing slip will be printed for each shipment and if multiple packages are required for one shipment they will be linked to the same master tracking number if supported by the carrier.

Entity Properties

Shipment
Shipment Item
Package
Shipment Track (deprecated)

`shipment.search`

shipment.search(null|object $filters, array $options = [], null|string|object $fields = []) Retrieve list of shipments by filters. Shipment data can be customized by specifying properties to retrieve.

Some accounts may still receive deprecated shipment status names in shipment.search responses because of a compatibility flag from the 2023 package tracking migration. If your integration receives loaded, treat it as equivalent to shipped and support both the old and new status names. See the Package Tracking Migration Guide for the full status mapping.

Parameters

null | object

null - Retrieve list of all shipments.
object - Retrieve list of shipments using specified Search Filters. Allowed properties for filtering: “shipment_id”, “warehouse_id”, “order_unique_id”, “order_ref”, “order_id”, “store_code”, “created_at”, “updated_at”, “packed_at”, “status”, “shipment_type”.

null | array

null - No options will be applied.
object - Apply specified Search Options.

null | string | object

null - Retrieve only “shipment_id”, “order_unique_id”, and “order_ref” properties.
string '*' - Retrieve all properties excluding “shipping_address”, “items”, “packages”, “tracking_numbers”, and “serial_number_data”.
object - List of properties to retrieve in addition to “shipment_id”, “order_unique_id”, and “order_ref”. List may include ’*’. Example:

["*", "shipping_address", "packages"]

See Shipment Properties.

Return Value

An object with the following properties:

array

An array of objects. Each object will contain the specified (or default if no fields parameter was given) Shipment Properties.

integer

The total number of shipments matching the given filters. Omitted if skip_totals is enabled.

integer

The total number of pages. Omitted if skip_totals is enabled.

Example Request

Request

{
    "jsonrpc": 2.0,
    "id": 1234,
    "method": "call",
    "params": [
        "97ca4f4a5cdca59e9dd0fe52e28bf7cf",
        "shipment.search",
        [
            { "status": "picked" },
            { "limit": 1 },
            ["status", "created_at", "updated_at"]
        ]
    ]
}

Example Response

Response

{
    "jsonrpc": 2.0,
    "id": 1234,
    "result": {
        "results": [
            {
                "shipping_method": "fedex_FEDEX_GROUND",
                "tpb_group_id": null,
                "order_unique_id": "1100000005",
                "order_ref": null,
                "shipment_id": "1100000002",
                "warehouse_id": "1",
                "status": "picked",
                "created_at": "2018-01-26T15:11:08+00:00",
                "updated_at": "2020-03-20T17:01:15+00:00"
            }
        ],
        "totalCount": 28,
        "numPages": 28
    }
}

Example Request (skip_totals)

Request

{
    "jsonrpc": 2.0,
    "id": 1234,
    "method": "call",
    "params": [
        "97ca4f4a5cdca59e9dd0fe52e28bf7cf",
        "shipment.search",
        [
            { "status": "picked" },
            { "limit": 1, "skip_totals": 1 },
            ["status", "created_at", "updated_at"]
        ]
    ]
}

Example Response (skip_totals)

Response

{
    "jsonrpc": 2.0,
    "id": 1234,
    "result": {
        "results": [
            {
                "shipping_method": "fedex_FEDEX_GROUND",
                "tpb_group_id": null,
                "order_unique_id": "1100000005",
                "order_ref": null,
                "shipment_id": "1100000002",
                "warehouse_id": "1",
                "status": "picked",
                "created_at": "2018-01-26T15:11:08+00:00",
                "updated_at": "2020-03-20T17:01:15+00:00"
            }
        ]
    }
}

Error Codes

code	message
101	Invalid filters given. Details in error message.

`shipment.info`

shipment.info(string $shipment) Retrieve all shipment information.

Parameters

string

Shipment ID. Can be retrieved from the order “shipments” property.

Return Value

Shipment information.

Example Request

Request

{
    "jsonrpc": 2.0,
    "id": 1234,
    "method": "call",
    "params": [
        "97ca4f4a5cdca59e9dd0fe52e28bf7cf",
        "shipment.info",
        "100000020"
    ]
}

Example Response

Response

{
    "jsonrpc": 2.0,
    "id": 1234,
    "error": null,
    "result": 
    {
        "shipment_id": "100000020",
        "warehouse_id": 1,
        "order_unique_id": "10000015",
        "order_ref": "ABC-54321",
        "store_code": "acme",
        "status": "packing",
        "shipment_type": "parcel",
        "total_weight": "13.2300",
        "total_weight_unit": "lb",
        "total_item_weight": "12.1100",
        "total_item_weight_unit": "lb",
        "total_qty": "2.0000",
        "shipped_weight": "13.2300",
        "shipped_weight_unit": "lb",
        "source": "123",
        "tpb_group_id": 1,
        "manifest_courier_code": "fedex",
        "manifest_courier_name": "FedEx",
        "created_at": "2014-07-24T18:51:18+00:00",
        "updated_at": "2014-07-24T18:51:18+00:00",
        "items": [
            {
                "sku": "product2",
                "name": "product2",
                "weight": "12.0500",
                "weight_unit": "lb",
                "qty": "1.0000",
                "qty_picked": "1.0000",
                "qty_shipped": "0.0000",
                "order_item_id": 121,
                "package_data": [
                    {"order_item_id": 121, "label": "Serial Number - 8 Characters", "value": "55285368"}
                ],
                "lot_data": [
                    {"lot_id": 456, "sku": "product2", "lot_number": "83CBC2", "expiration_date": "2021-10-05", "origination_date": "2019-01-23", "qty": "1.0000"}
                ]
            },
            {
                "sku": "product1",
                "name": "product1",
                "weight": "1.2300",
                "weight_unit": "lb",
                "qty": "1.0000",
                "qty_picked": "1.0000",
                "qty_shipped": "1.0000",
                "order_item_id": 122,
                "package_data": [
                    {"order_item_id": 122, "label": "Serial Number - 8 Characters", "value": "55285442"}
                ],
                "lot_data": [
                    {"lot_id": 789, "sku": "product1", "lot_number": "83CCC2", "expiration_date": "2021-10-25", "origination_date": "2019-01-23", "qty": "1.0000"}
                ],
                "ssccs": [
                    {"sscc": "508101336500131005", "package_index": 0}
                ]
            }
        ],
        "packages": [
            {
                "warehouse_id": "1",
                "shipment_id": "1100000061",
                "shipment_status": "packed",
                "status": "packed",
                "carrier": "fedex",
                "created_at": "2014-07-24T18:51:18+00:00",
                "tracking_added_at": "2014-07-24T18:51:18+00:00",
                "shipped_at": "2014-07-24T18:51:18+00:00",
                "delivered_at": "2014-07-24T18:51:18+00:00",
                "weight": "13.2300",
                "weight_unit": "lb",
                "billable_weight": "14",
                "billable_weight_unit": "lb",
                "dimensional_weight_divisor": "139",
                "dimensional_weight_divisor_unit": "in^3/lb",
                "dimensional_weight": "14",
                "rating_weight_unit": "lb",
                "dimensions": {
                    "length": "16.000",
                    "width": "12.000",
                    "height": "8.000"
                },
                "dimension_unit": "in",
                "tracking": [
                    {
                        "number": "800027315160887",
                        "description": "FedEx International Economy",
                        "track_url": "https://www.fedex.com/apps/fedextrack/?action=track&tracknumbers=800027315160887"
                    }
                ],
                "order_items": [
                    {
                        "order_item_id": "122",
                        "order_item_ref": null,
                        "sku": "product1",
                        "quantity": "1.0000"
                    }
                ],
                "package_items": [
                    {
                        "order_item_id": "122",
                        "sku": "product1",
                        "quantity": "1.0000"
                    }
                ],
                "package_data": [
                    {"order_item_id": 121, "label": "Serial Number - 8 Characters", "value": "55285368"},
                    {"order_item_id": 122, "label": "Serial Number - 8 Characters", "value": "55285442"}
                ],
                "serial_number_data": [
                    {
                        "serial_id": "1",
                        "identifier": "123456123456",
                        "sku": "product1",
                        "product_id": "7"
                    }
                ]
            }
        ],
        "tracking_numbers": [
            {
                "carrier": "fedex",
                "description": "FedEx International Economy",
                "number": "800027315160887",
                "date": "2014-07-24T18:51:18+00:00",
                "items": [
                    {"sku": "product1", "quantity": "1.0000" },
                    {"sku": "product2", "quantity": "1.0000" }
                ],
                "weight": "13.2300",
                "weight_unit": "lb"
            }
        ],
        "custom_fields": {
            "freight_broker": { "id": 15, "label": "FreightClub" },
            "hazmat_inspected_by": { "value": 414 }
        }
    }
}

Error Codes

code	message
100	Requested shipment does not exist.

`shipment.update`

shipment.update (string $shipment, object $shipmentData, object $customFields) Update shipment information.

Parameters

string

Shipment ID. Can be retrieved from the order “shipments” property.

object

Shipment data. Allowed properties: source.

object

Shipment Custom Field Operations (see Shipment Custom Field Operations).

Shipment Custom Field Operations

An object with an operation name as the key and an object containing the Shipment Custom Field) data for all operations except the remove operation. The remove operation only requires a list of custom field codes. Allowed operations: set, add, remove, add_option, remove_option.

set - Replace all values.
add - Add new fields to existing, replace old values.
remove - Remove only fields specified.
add_option - Multi-selects only. Add an option without unsetting existing options.
remove_option - Multi-selects only. Remove an option without unsetting other options not listed.

Return Value

true if shipment was successfully updated.

Example Request

Request

{
    "jsonrpc": 2.0,
    "id": 1234,
    "method": "call",
    "params": [
        "97ca4f4a5cdca59e9dd0fe52e28bf7cf",
        "shipment.update",
        [
            "100000020",
            {
                "source": "123456"
            }
        ]
    ]
}

Example Response

Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result" : true
}

Error Codes

code	message
100	Requested shipment does not exist.
102	Invalid data given. Details in error message.

Entity Properties

Shipment Properties

Show Shipment Properties

string

The “Shipment ID” property. This number may appear on the packing slip as the “Packing Slip #”.

integer

The internal warehouse ID.

string

The “unique_id” property for the order associated with this shipment.

string

The user-specified order “order_ref” field.

string

The store code used to place the order.

string

The “Status” property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided. Some accounts may receive the deprecated compatibility value loaded, which is equivalent to shipped.

string

The “Shipment Type” property. Allowed values: parcel, freight.

string

The “Source” property.

string

The estimated total weight of the shipment including packaging.

string

The unit of measure used for total_weight. See: Weight Units.

string

The “Total Item Weight” property.

string

The unit of measure used for total_item_weight. See: Weight Units.

string

The “Total Quantity” property.

string

The “Shipped Weight” property.

string

The unit of measure used for shipped_weight. See: Weight Units.

string

This field is used for storing association data for integrations.

string

The Third Party Billing Account Group ID.

string

The date the shipment is intended to be shipped. This is computed based on when the order was “Ready to Ship” and the configured cutoff times for same day shipping.

string

The Standard Carrier Alpha Code.

string

The manifest courier code.

string

The manifest courier name.

string

Date and time when the shipment was created in ISO 8601 format.

string

Date and time when the shipment was last updated in ISO 8601 format.

string

Date and time when all packages were packed in ISO 8601 format.

string

Date and time when all packages were shipped from the warehouse in ISO 8601 format.

string

Date and time when all packages were delivered in ISO 8601 format.

string

Date and time the tracking was added in ISO 8601 format.

object

Object of Shipping Address properties.

array

Array of Shipment Item objects.

array

Array of Package objects.

array

Array of Shipment Track objects. This field is deprecated. Please use ‘packages’ instead.

object

Object with Custom Fields. See Shipment Custom Field.

integer

The internal ID of the parent order’s linked B2B Retailer, or null. Makes the link visible without loading the retailer.

object

The parent order’s linked Retailer, or null. Excluded from shipment.search results by default; request it explicitly via the fields parameter.

Show Retailer

integer

The internal retailer ID.

string

The retailer code.

string

The retailer name.

integer

The internal ID of the parent order’s linked Retailer Ship-To Location, or null. Makes the link visible without loading the location.

object

The parent order’s linked retailer ship-to location, or null. Excluded from shipment.search results by default; request it explicitly via the fields parameter.

Show Retailer Ship-To Location

integer

The internal ship-to location ID.

string

The canonical qualifier scheme for the code. See the Retailer Ship-To Location allowed values.

string

The ship-to location code.

string

Optional display label.

string

Location type. One of dc, store, drop_ship, other.

Shipment Item Properties

Show Shipment Item Properties

string

The “SKU” property.

string

The “Name” property.

string

The “Weight” property.

string

The unit of measure used for weight. See: Weight Units.

string

The “Quantity” property.

string

The “Picked” quantity.

string

The “Shipped” quantity.

string

The “Cancel Requested” quantity. Denotes the quantity to be cancelled if cancellation request is confirmed.

string

The “Canceled” quantity.

integer

The internal order item ID.

array

The “Package Data” property.

array

The Lot Data for the Shipment Item.

integer

The internal Lot ID.

string

The SKU of the Product assigned to the Lot. This may differ from the Shipment Item sku for BOM and quantity-type workflows.

string

The Lot Number.

string

The Lot expiration date.

string

The Lot origination date.

string

The quantity assigned to the Lot.

array

The item SSCCs.

Package Properties

Show Package Properties

string

The ID of the warehouse associated with the package.

string

The “Status” property. Allowed values: packing, tracking_required, packed, manifested, shipped, delivered.

string

The “Shipment ID” property. This number may appear on the packing slip as the “Packing Slip #” and is used for the Shipment API calls.

string

The “Shipment Status” property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided.

string

Carrier code.

string

Date and time when the package was shipped from the warehouse in ISO 8601 format.

string

Date and time when the package was delivered in ISO 8601 format.

string

The weight of the package.

string

The unit of measure used for weight. See: Weight Units.

integer

The billable weight of the package.

string

The unit of measure used for billable_weight. See: Weight Units.

string

The dimensional weight divisor of the package.

string

The dimensional weight divisor unit. See: Dimensional Divisor Units.

string

The dimensional weight of the package.

string

The unit of measure used for dimensional_weight. See: Weight Units.

object

The length, width, and height of the package.

string

The unit of measure used for length, width, and height in dimensions. See: Length Units.

string

The Serial Shipping Container Code.

array

An array of tracking objects. The “number” property contains the tracking number. The “description” property contains the shipping method name. The “track_url” property will contain a URL to the carrier’s tracking page if applicable.

array

An array of order items contained in the package. These items may be different from those in “package_items” if the order was fulfilled using a Bill of Materials. “order_item_id” is the unqiue identifier for the order item. “order_item_ref” is an optional user supplied reference for the order item. “sku” is the order item’s SKU. “quantity” is the quantity of the order item in the package.

array

An array of items contained in the package. These items may be different from those in “order_items” if the order was fulfilled using a Bill of Materials. “order_item_id” is the unqiue identifier of the related order item. “sku” is the package item’s SKU. “quantity” is the quantity of the item in the package.

array

The “Package Data” property.

array

The “Packaging” property.

array

Array of serial numbers. See Serial Number properties.

Shipment Track Properties

Show Shipment Track Properties

string

The carrier code.

string

The method description (with the carrier name).

string

The carrier’s tracking number.

string

The date and time the tracking number was created.

array

SKUs and quantities of the related package items.

string

The weight of the package.

string

The unit of measure used for weight. See: Weight Units.

Serial Number Properties

Show Serial Number Properties

string

The “Serial ID” property.

string

The unique identifier of the serial number.

string

The SKU of the product associated with the serial number.

string

The ID of the product associated with the serial number.

Shipment Custom Field

An object with a Custom Field code as the key and the Custom Field data as the value. The value format depends on the Custom Field input type. "custom_fields": { ... } To find out what fields are available see Shipment Custom Fields — shipment_custom_field.list

Show Shipment Custom Field

object

Maximum number of characters is 1024.

{ "main_sku" : { "value" : "product2" } }

object

{ "shipment_details" : { "value" : "Long multiline 
shipment details 
here." } }

object

{ "number_of_skus" : { "value" : 5 } }

{ "length_and_girth" : { "value" : 54.25 } }

object

{ "cost_of_goods" : { "amount" : 105.95 } }

object

Select input type data must be an object with label or id key or both.

{ "claim_reason" : { "id" : 13 } }

Preferred. An option is set by id.

{ "claim_reason" : { "label" : "Damaged in shipping" } }

An option is set by label.

{ "claim_reason" : { "id" : 13, "label" : "Damaged in shipping" } }

An option is set by id and label. The id and the label must refer to the same option.

array

Multi-select input type data must be an array of objects with label or id key or both.

{ "claim_reasons" : [ { "id" : 13 }, { "id" : 14 } ] }

Preferred. An option is set by id.

{ "claim_reasons" : [ { "label" : "Damaged in shipping" }, { "label" : "Did not fit" } ] }

An option is set by label.

{ "claim_reasons" : [ { "id" : 13, "label" : "Damaged in shipping" }, { "id" : 14, "label" : "Did not fit" } ] }

An option is set by id and label. The id and the label must refer to the same option.

object

{ "allow_mailer" : { "value" : true } }

object

Must be in Y-m-d format.

{ "desired_delivery_date" : { "value" : "2023-01-23" } }

object

Must be a client user id.

{ "created_by" : { "value" : 5 } }

object

Must be an admin user id.

{ "created_by" : { "value" : 7 } }

object

Must be a valid email address. Maximum number of characters is 1024.

{ "custom_email" : { "value" : "john.doe@example.com" } }

object

Must be a valid URL. Maximum number of characters is 1024.

{ "documentation_url" : { "value" : "https://example.com" } }

Get Started

Common Features

Shipping

Receiving

Inventory

System

Methods

Entity Properties

`shipment.search`

Parameters

Return Value

Example Request

Example Response

Example Request (skip_totals)

Example Response (skip_totals)

Error Codes

`shipment.info`

Parameters

Return Value

Example Request

Example Response

Error Codes

`shipment.update`

Parameters

Shipment Custom Field Operations

Return Value

Example Request

Example Response

Error Codes

Entity Properties

Shipment Properties

Shipment Item Properties

Package Properties

Shipment Track Properties

Serial Number Properties

Shipment Custom Field

​Methods

​Entity Properties

​shipment.search

​Parameters

​Return Value

​Example Request

​Example Response

​Example Request (skip_totals)

​Example Response (skip_totals)

​Error Codes

​shipment.info

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​shipment.update

​Parameters

​Shipment Custom Field Operations

​Return Value

​Example Request

​Example Response

​Error Codes

​Entity Properties

​Shipment Properties

​Shipment Item Properties

​Package Properties

​Shipment Track Properties

​Serial Number Properties

​Shipment Custom Field

Methods

Entity Properties

`shipment.search`

Parameters

Return Value

Example Request

Example Response

Example Request (skip_totals)

Example Response (skip_totals)

Error Codes

`shipment.info`

Parameters

Return Value

Example Request

Example Response

Error Codes

`shipment.update`

Parameters

Shipment Custom Field Operations

Return Value

Example Request

Example Response

Error Codes

Entity Properties

Shipment Properties

Shipment Item Properties

Package Properties

Shipment Track Properties

Serial Number Properties

Shipment Custom Field