Shipment

Methods

Entity Properties

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.

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

orderdescription
0
  • null - Retrieve list of all shipments.
  • object - Retrieve list of shipments using specified 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".
1
  • null - No options will be applied.
  • object - Apply specified options.
2
  • null - Retrieve only "shipment_id", "order_unique_id", and "order_ref" properties.
  • string '*' - Retrieve all properties excluding "shipping_address", "items", "packages" and "tracking_numbers".
  • object - List of properties to retrieve in addition to "shipment_id", "order_unique_id", and "order_ref". List may include '*'.

See "Shipment Properties". Example: ["*", "shipping_address", "packages"]

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 (string $shipment)

Retrieve all shipment information.

Parameters

orderdescription
0 string - Shipment ID. Can be retrieved from the order "shipments" property.

Return Value

Shipment information.

Example Request

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

Example 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",
        "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,
        "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"}
                ]
            }
        ],
        "packages": [
            {
                "warehouse_id": "1",
                "shipment_id": "1100000061",
                "shipment_status": "packed",
                "status": "packed",
                "carrier": "fedex",
                "manifest_courier_code": "fedex",
                "manifest_courier_name": "FedEx",
                "timestamp": "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",
                "dimensional_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"}
                ]
            }
        ],
        "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"
            }
        ]
    }
}

Error Codes

code message
100 Requested shipment does not exist.

shipment.update (string $shipment, object $shipmentData)

Update shipment information.

Parameters

orderdescription
0 string - Shipment ID. Can be retrieved from the order "shipments" property.
1 object - Shipment data.
Allowed properties: source.

Return Value

true if shipment was successfully updated.

Example Request

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

Example 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

shipment_id 
{ "shipment": "100000005" }
The "Shipment ID" property. This number may appear on the packing slip as the "Packing Slip #".
warehouse_id 
{ "warehouse_id": 1 }
The internal warehouse ID.
order_unique_id 
{ "order_unique_id": "100000010" }
The "unique_id" property for the order associated with this shipment.
order_ref 
{ "order_ref": "ABC-54321" }
The user-specified order "order_ref" field.
store_code 
{ "store_code": "acme" }
The store code used to place the order.
status 
{ "status": "packing" }
The "Status" property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided.
source 
{ "source": "123" }
The "Source" property.
total_weight 
{ "total_weight": "13.2300" }
The estimated total weight of the shipment including packaging.
total_weight_unit 
{ "total_weight_unit": "lb" }
The unit of measure used for total_weight. See: Weight Units.
total_item_weight 
{ "total_weight": "12.1100" }
The "Total Item Weight" property.
total_item_weight_unit 
{ "total_item_weight_unit": "lb" }
The unit of measure used for total_item_weight. See: Weight Units.
total_qty 
{ "total_qty": "2.0000" }
The "Total Quantity" property.
shipped_weight 
{ "shipped_weight": "13.2300" }
The "Shipped Weight" property.
shipped_weight_unit 
{ "shipped_weight_unit": "lb" }
The unit of measure used for shipped_weight. See: Weight Units.
source 
{ "source": "123" }
This field is used for storing association data for integrations.
tpb_group_id 
{ "tpb_group_id": "1" }
The Third Party Billing Account Group ID.
target_ship_date 
{ "target_ship_date": "2014-07-24" }
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 
{ "scac": "UPSN" }
The Standard Carrier Alpha Code.
created_at 
{ "created_at": "2014-07-24T18:51:18+00:00" }
Date and time when the shipment was created in ISO 8601 format.
updated_at 
{ "updated_at": "2014-07-24T18:51:18+00:00" }
Date and time when the shipment was last updated in ISO 8601 format.
packed_at 
{ "packed_at": "2014-07-24T18:51:18+00:00" }
Date and time when all packages were packed in ISO 8601 format.
shipped_at 
{ "shipped_at": "2014-07-24T18:51:18+00:00" }
Date and time when all packages were shipped from the warehouse in ISO 8601 format.
delivered_at 
{ "delivered_at": "2014-07-24T18:51:18+00:00" }
Date and time when all packages were delivered in ISO 8601 format.
shipping_address Object of Shipping Address properties.
items Array of Shipment Item objects.
packages Array of Package objects.
tracking_numbers Array of Shipment Track objects. This field is deprecated. Please use 'packages' instead.

Shipment Item Properties

sku 
{ "sku": "product1" }
The "SKU" property.
name 
{ "name": "product1" }
The "Name" property.
weight 
{ "weight": "12.0000" }
The "Weight" property.
weight_unit 
{ "weight_unit": "lb" }
The unit of measure used for weight. See: Weight Units.
qty 
{ "qty": "1.0000" }
The "Quantity" property.
qty_picked 
{ "qty_picked": "1.0000" }
The "Picked" quantity.
qty_shipped 
{ "qty_shipped": "1.0000" }
The "Shipped" quantity.
qty_cancel_requested 
{ "qty_cancel_requested": "1.0000" }
The "Cancel Requested" quantity. Denotes the quantity to be cancelled if cancellation request is confirmed.
qty_canceled 
{ "qty_canceled": "1.0000" }
The "Canceled" quantity.
order_item_id 
{ "order_item_id": 2 }
The internal order item ID.
package_data 
[
    {"label": "Serial Number - 8 Characters", "value": "55285368"},
    {"label": "Serial Number - 8 Characters", "value": "55285368"}
]
The "Package Data" property.
lot_data 
[
    {"lot_number": "P7KPKDN212B", "expiration_date": "2020-11-20", "origination_date": "2019-01-23", "qty": "1.0000"}
]
The "Lot Data" property.

Package Properties

warehouse_id 
{ "warehouse_id": "1" }
The ID of the warehouse associated with the package.
status 
{ "status": "packed" }
The "Status" property. Allowed values: packing, tracking_required, packed, manifested, shipped, delivered.
shipment_id 
{ "shipment_id": "100000005" }
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 
{ "shipment_status": "packing" }
The "Shipment Status" property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided.
carrier 
{ "carrier": "ups" }
Carrier code.
manifest_courier_code 
{ "manifest_courier_code" : "ups" }
Manifest courier code.
manifest_courier_name 
{ "manifest_courier_name" : "UPS" }
Manifest courier name.
timestamp 
{ "timestamp": "2019-01-14T14:29:31+00:00" }
The date and time when the package was created in ISO 8601 format.
shipped_at 
{ "shipped_at" : "2019-01-14T14:29:31+00:00" }
Date and time when the package was shipped from the warehouse in ISO 8601 format.
delivered_at 
{ "delivered_at" : "2019-01-14T14:29:31+00:00" }
Date and time when the package was delivered in ISO 8601 format.
weight 
{ "weight": "16.900" }
The weight of the package.
weight_unit 
{ "weight_unit": "lb" }
The unit of measure used for weight. See: Weight Units.
billable_weight 
{ "billable_weight" : 20 }
The billable weight of the package.
billable_weight_unit 
{ "billable_weight_unit" : "lb" }
The unit of measure used for billable_weight. See: Weight Units.
dimensional_weight_divisor 
{ "dimensional_weight_divisor": "139" }
The dimensional weight divisor of the package.
dimensional_weight_divisor_unit 
{ "dimensional_weight_divisor_unit": "in^3/lb" }
The unit of measure used for dimensional_weight_divisor. See: Dimensional Divisor Units.
dimensional_weight 
{ "dimensional_weight": "12" }
The dimensional weight of the package.
dimensional_weight_unit 
{ "dimensional_weight_unit": "lb" }
The unit of measure used for dimensional_weight. See: Weight Units.
dimensions 
{ 
    "dimensions": {
        "length": "16.000",
        "width": "12.000",
        "height": "8.000"
    } 
}
The length, width, and height of the package.
dimension_unit 
{ "dimension_unit": "in" }
The unit of measure used for length, width, and height in dimensions. See: Length Units.
sscc 
{ "sscc" : "008012349999999997" }
The Serial Shipping Container Code.
tracking 
[
    { 
        "number" : "1Z49R7V80308849438", 
        "description" : "UPS Ground",
        "track_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z49R7V80308849438"
    }, { 
        "number" : "1Z49R7V29475663003", 
        "description" : "UPS Ground",
        "track_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z49R7V29475663003"
    }
]
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 
[
    {
        "order_item_id": "117",
        "order_item_ref": "10",
        "sku: "product1",
        "quantity: "2.0000"
    }, {
        "order_item_id": "118",
        "order_item_ref": null,
        "sku: "product2",
        "quantity: "2.0000"
    } 
]
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 
[
    {
        "order_item_id": "117",
        "sku: "product1",
        "quantity: "2.0000" 
    }, {
        "order_item_id": "118",
        "sku: "product2",
        "quantity: "2.0000"
    }
]
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 
[
    {
        "order_item_id: "117", 
        "label": "Serial Number - 8 Characters", 
        "value": "55285368"
    }, {
       "order_item_id: "118", 
       "label": "Serial Number - 8 Characters", 
       "value": "55285369"
   }
]
The "Package Data" property.
packaging 
[
    {
        "sku: "packaging1",
        "quantity: "2.0000"
    }
]
The "Packaging" property.

Shipment Track Properties

carrier 
{ "carrier": "fedex" }
The carrier code.
description 
{ "description": "FedEx Express Saver" }
The method description (with the carrier name).
number 
{ "number": "800027315160887" }
The carrier's tracking number.
date 
{ "date": "2014-07-24T18:51:18+00:00" }
The date and time the tracking number was created.
items 
[
    {"sku": "product1", "quantity": 1 },
    {"sku": "product2", "quantity": 1 }
]
SKUs and quantities of the related package items.
weight 
{ "weight": "13.23" }
The weight of the package.
weight_unit 
{ "weight_unit": "lb" }
The unit of measure used for weight. See: Weight Units.