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.

Parameters

filters

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

options

null | array

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

fields

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 array of objects. Each object will contain the specified (or default if no fields parameter was given) Shipment Properties.

Error Codes

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

`shipment.info`

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

Parameters

shipment

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_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_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

<ParamField path="shipment" type="string">
    Shipment ID. Can be retrieved from the order "shipments" property.
</ParamField>
<ParamField path="shipmentData" type="object">
    Shipment data.
    Allowed properties: source.
</ParamField>
<ParamField path="customFields" type="object">
    Shipment Custom Field Operations (see [Shipment Custom Field Operations](#shipment-custom-field-operations)).
</ParamField>

### Shipment Custom Field Operations

An object with an operation name as the key and an object containing the [Shipment Custom Field](#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

```json title="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

shipment_id

string

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

warehouse_id

integer

The internal warehouse ID.

order_unique_id

string

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

order_ref

string

The user-specified order “order_ref” field.

store_code

string

The store code used to place the order.

status

string

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

shipment_type

string

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

source

string

The “Source” property.

total_weight

string

The estimated total weight of the shipment including packaging.

total_weight_unit

string

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

total_item_weight

string

The “Total Item Weight” property.

total_item_weight_unit

string

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

total_qty

string

The “Total Quantity” property.

shipped_weight

string

The “Shipped Weight” property.

shipped_weight_unit

string

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

source

string

This field is used for storing association data for integrations.

tpb_group_id

string

The Third Party Billing Account Group ID.

target_ship_date

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.

scac

string

The Standard Carrier Alpha Code.

manifest_courier_code

string

The manifest courier code.

manifest_courier_name

string

The manifest courier name.

created_at

string

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

updated_at

string

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

packed_at

string

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

shipped_at

string

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

delivered_at

string

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

tracking_added_at

string

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

shipping_address

object

Object of Shipping Address properties.

items

array

Array of Shipment Item objects.

packages

array

Array of Package objects.

tracking_numbers

array

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

custom_fields

object

Object with Custom Fields. See Shipment Custom Field.

Shipment Item Properties

Show Shipment Item Properties

sku

string

The “SKU” property.

name

string

The “Name” property.

weight

string

The “Weight” property.

weight_unit

string

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

qty

string

The “Quantity” property.

qty_picked

string

The “Picked” quantity.

qty_shipped

string

The “Shipped” quantity.

qty_cancel_requested

string

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

qty_canceled

string

The “Canceled” quantity.

order_item_id

integer

The internal order item ID.

package_data

array

The “Package Data” property.

lot_data

array

The “Lot Data” property.

ssccs

array

The item SSCCs.

Package Properties

Show Package Properties

warehouse_id

string

The ID of the warehouse associated with the package.

status

string

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

shipment_id

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.

shipment_status

string

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

carrier

string

Carrier code.

shipped_at

string

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

delivered_at

string

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

weight

string

The weight of the package.

weight_unit

string

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

billable_weight

integer

The billable weight of the package.

billable_weight_unit

string

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

dimensional_weight_divisor

string

The dimensional weight divisor of the package.

dimensional_weight_divisor_unit

string

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

dimensional_weight

string

The dimensional weight of the package.

rating_weight_unit

string

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

dimensions

object

The length, width, and height of the package.

dimension_unit

string

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

sscc

string

The Serial Shipping Container Code.

tracking

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.

order_items

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.

package_items

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.

package_data

array

The “Package Data” property.

packaging

array

The “Packaging” property.

serial_number_data

array

Array of serial numbers. See Serial Number properties.

Shipment Track Properties

Show Shipment Track Properties

carrier

string

The carrier code.

description

string

The method description (with the carrier name).

number

string

The carrier’s tracking number.

date

string

The date and time the tracking number was created.

items

array

SKUs and quantities of the related package items.

weight

string

The weight of the package.

weight_unit

string

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

Serial Number Properties

Show Serial Number Properties

serial_id

string

The “Serial ID” property.

identifier

string

The unique identifier of the serial number.

sku

string

The SKU of the product associated with the serial number.

product_id

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

text

object

Maximum number of characters is 1024.

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

multiline-text

object

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

number

object

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

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

currency

object

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

select

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.

multiselect

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.

boolean

object

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

date

object

Must be in Y-m-d format.

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

client-user

object

Must be a client user id.

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

admin-user

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" } }

url

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

Error Codes

`shipment.info`

Parameters

Return Value

Example Request

Example Response

Example Response

Error Codes

Entity Properties

Shipment Properties

Shipment Item Properties

Package Properties

Shipment Track Properties

Serial Number Properties

Shipment Custom Field

Get Started

Common Features

Shipping

Receiving

Inventory

System

​Methods

​Entity Properties

​shipment.search

​Parameters

​Return Value

​Error Codes

​shipment.info

​Parameters

​Return Value

​Example Request

​Example Response

​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

Error Codes

`shipment.info`

Parameters

Return Value

Example Request

Example Response

Example Response

Error Codes

Entity Properties

Shipment Properties

Shipment Item Properties

Package Properties

Shipment Track Properties

Serial Number Properties

Shipment Custom Field