Delivery Label

Methods

Entity Properties

delivery_label.info (int $labelId, array $fields = [])

Retrieve delivery label information.

Parameters

orderdescription
0 Delivery label internal id
1
  • null - Basic label data.
  • array - Array of fields. Allowed: "packages", "destination_address", "origin_address"

Return Value

An object with Delivery Label Properties.

Example Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "12e6f7398eb7a992219477aaa771725d",
        "delivery_label.info",
        [
            "2",
            [
                "packages",
                "destination_address",
                "origin_address",
                "files"
            ]
        ]
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result": [
        {
            "label_id": "8",
            "delivery_id": "26",
            "warehouse_id": "1",
            "status": "valid",
            "shipping_method": "ups_03",
            "created_at": "2021-01-20T10:03:55+00:00",
            "updated_at": "2021-01-20T10:04:01+00:00",
            "packages": [
                {
                    "warehouse_id": "1",
                    "label_id": "8",
                    "carrier": "ups",
                    "weight": "18.000",
                    "weight_unit": "lb",
                    "dimensions": {
                        "length": "10.000",
                        "width": "11.000",
                        "height": "12.000"
                    },
                    "dimension_unit": "in",
                    "tracking": [
                        {
                            "number": "1Z49R7V89024431506",
                            "description": "UPS Ground"
                        }
                    ],
                    "package_items": [
                        {
                            "delivery_item_id": 2,
                            "sku": "O-VS-Oregano-p3",
                            "quantity": "4.000"
                        },
                        {
                            "delivery_item_id": 3,
                            "sku": "O-VS-Mint-p2",
                            "quantity": "4.000"
                        },
                        {
                            "delivery_item_id": 5,
                            "sku": "VS-Bags-p1",
                            "quantity": "4.000"
                        }
                    ]
                }
            ],
            "destination_address": {
                "region": "New York",
                "postcode": "13088",
                "lastname": "Marquez",
                "street": "4616 Crossroads Park Dr",
                "city": "Liverpool",
                "email": null,
                "telephone": "865-971-4663",
                "firstname": "Sherlock",
                "company": null,
                "classification": "com",
                "is_valid": null,
                "country": "US"
            },
            "origin_address": {
                "region": "New York",
                "postcode": "10036",
                "lastname": "Gates",
                "street": "11 Times Square",
                "city": "New York",
                "email": null,
                "telephone": "212.245.2100",
                "firstname": "Bill",
                "company": "Microsoft",
                "classification": null,
                "is_valid": null,
                "country": "US"
            },
            "files": {
                "label": {
                    "type": "pdf",
                    "data": "base64encoded..."
                },
                "auxiliary_label": {
                    "type": "pdf",
                    "data": "bas64encoded..."
                },
                "customs_documents": null
            }
        }
    ]
}

Error Codes

code message
100 Requested delivery label does not exist.

delivery_label.search (object|null $filters = [], array|null $options = [], array|null $fields = [])

An array of objects. Each object will contain Delivery Label Properties.

Parameters

orderdescription
0
  • null - Retrieve list of all delivery labels.
  • object - Retrieve list of delivery labels using specified filters.
1
  • null - No options will be applied.
  • object - Apply specified options.
2
  • null - Basic label data.
  • array - Array of fields. Allowed: "packages", "destination_address", "origin_address"

Return Value

An array of objects. Each object will contain “Delivery Label Properties”.

Example Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "12e6f7398eb7a992219477aaa771725d",
        "delivery_label.search",
        [
            { "label_id": { "eq" : "2" } },
            {
                "limit": 100,
                "page": 1
            },
            [
                "packages",
                "destination_address",
                "origin_address",
                "files"
            ]
        ]
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result": {
        "results": [
            {
                "label_id": "2",
                "delivery_id": "22",
                "warehouse_id": "1",
                "status": "valid",
                "shipping_method": "ups_03",
                "created_at": "2021-01-18T13:57:25+00:00",
                "updated_at": "2021-01-18T13:57:29+00:00",
                "packages": [
                    {
                        "warehouse_id": "1",
                        "label_id": "2",
                        "carrier": "ups",
                        "weight": "45.000",
                        "weight_unit": "lb",
                        "dimensions": {
                            "length": "10.000",
                            "width": "11.000",
                            "height": "12.000"
                        },
                        "dimension_unit": "in",
                        "tracking": [
                            {
                                "number": "1Z49R7V89024877071",
                                "description": "UPS Ground"
                            }
                        ],
                        "package_items": [
                            {
                                "delivery_item_id": "68",
                                "sku": "O-VS-Oregano-p3",
                                "quantity": "10.000"
                            },
                            {
                                "delivery_item_id": "69",
                                "sku": "O-VS-Mint-p2",
                                "quantity": "10.000"
                            },
                            {
                                "delivery_item_id": "70",
                                "sku": "VS-Bags-p1",
                                "quantity": "10.000"
                            }
                        ]
                    }
                ],
                "destination_address": {
                    "region": "New York",
                    "postcode": "13088",
                    "lastname": "Marquez",
                    "street": "4616 Crossroads Park Dr",
                    "city": "Liverpool",
                    "email": null,
                    "telephone": "865-971-4663",
                    "firstname": "Sherlock",
                    "company": null,
                    "classification": "com",
                    "is_valid": null,
                    "country": "US"
                },
                "origin_address": {
                    "region": "New York",
                    "postcode": "10036",
                    "lastname": "Gates",
                    "street": "11 Times Square",
                    "city": "New York",
                    "email": null,
                    "telephone": "212.245.2100",
                    "firstname": "Bill",
                    "company": "Microsoft",
                    "classification": null,
                    "is_valid": null,
                    "country": "US"
                },
                "files": {
                    "label": {
                        "type": "pdf",
                        "data": "base64encoded..."
                    },
                    "auxiliary_label": {
                        "type": "pdf",
                        "data": "bas64encoded..."
                    },
                    "customs_documents": null
                }
            }
        ],
        "totalCount": 1,
        "numPages": 1
    }
}

Error Codes

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

delivery_label.create (string $incrementId, object $address, array $packages, object $options)

Create a new delivery label.

Parameters

orderdescription
0 Delivery internal id
1 Destination Address. See Delivery Label Address Properties.
2 Array of delivery label packages. See Delivery Label Package Properties.
3 Options. See Delivery Label Options.

Return Value

An object with Delivery Label Properties.

Example Request

{
    "jsonrpc":2.0,
    "id":1234,
    "method":"call",
    "params":[
        "12e6f7398eb7a992219477aaa771725d",
        "delivery_label.create",
        [
            "11000022",
            {
                "firstname" : "Bill",
                "lastname" : "Gates",
                "company" : "Microsoft",
                "street" : "11 Times Square",
                "city" : "New York",
                "region" : "NY",
                "postcode" : "10036",
                "country" : "US",
                "telephone" : "212.245.2100"
            },
            [
                {
                    "weight": "45.000",
                    "weight_unit": "lb",
                    "dimensions": {
                        "length": "10.000",
                        "width": "11.000",
                        "height": "12.000"
                    },
                    "dimension_unit": "in",
                    "package_items": [
                        {
                            "sku": "O-VS-Oregano-p3",
                            "quantity": "10.000"
                        },
                        {
                            "sku": "O-VS-Mint-p2",
                            "quantity": "10.000"
                        },
                        {
                            "sku": "VS-Bags-p1",
                            "quantity": "10.000"
                        }
                    ]
                }
            ],
            {
                "shipping_method":"ups_03",
                "return_service_type":"print_or_download"
            }
        ]
    ]
}

Example Response

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result": [
        {
            "label_id": "10",
            "delivery_id": "27",
            "warehouse_id": "1",
            "status": "valid",
            "shipping_method": "ups_03",
            "created_at": "2021-01-22T13:45:17+00:00",
            "updated_at": "2021-01-22T13:45:28+00:00",
            "packages": [
                {
                    "warehouse_id": "1",
                    "label_id": "10",
                    "carrier": "ups",
                    "weight": 45,
                    "weight_unit": "lb",
                    "dimensions": {
                        "length": 10,
                        "width": 11,
                        "height": 12
                    },
                    "dimension_unit": "in",
                    "tracking": [
                        {
                            "number": "1Z49R7V89013598741",
                            "description": "UPS Ground"
                        }
                    ],
                    "package_items": [
                        {
                            "delivery_item_id": "81",
                            "sku": "O-VS-Oregano-p3",
                            "quantity": 10
                        },
                        {
                            "delivery_item_id": "82",
                            "sku": "O-VS-Mint-p2",
                            "quantity": 10
                        },
                        {
                            "delivery_item_id": "83",
                            "sku": "VS-Bags-p1",
                            "quantity": 10
                        }
                    ]
                }
            ],
            "destination_address": {
                "firstname": "Sherlock",
                "lastname": "Marquez",
                "telephone": "865-971-4663",
                "street": "4616 Crossroads Park Dr",
                "city": "Liverpool",
                "postcode": "13088",
                "classification": "com",
                "region": "New York",
                "country": "US"
            },
            "origin_address": {
                "firstname": "Bill",
                "lastname": "Gates",
                "company": "Microsoft",
                "street": "11 Times Square",
                "city": "New York",
                "region": "New York",
                "postcode": "10036",
                "telephone": "212.245.2100",
                "email": null,
                "classification": null,
                "is_valid": null,
                "country": "US"
            },
            "files": {
                "label": {
                    "type": "pdf",
                    "data": "base64encoded..."
                },
                "auxiliary_label": {
                    "type": "pdf",
                    "data": "bas64encoded..."
                },
                "customs_documents": null
            }
        }
    ]
}

Error Codes

code message
100 Requested delivery label does not exist.
101 Invalid filters given. Details in error message.
102 Invalid data given. Details in error message.
103 Cannot void the delivery label. Details in error message.
104 An unexpected error occurred while creating the delivery label.
105 Requested delivery does not exist.

delivery_label.void (int $labelId)

Void delivery label.

Parameters

orderdescription
0 Delivery label internal id

Return Value

true if the Delivery Label was voided.

Example Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "12e6f7398eb7a992219477aaa771725d",
        "delivery_label.void",
        [
            "8"
        ]
    ]
}

Example Response

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

Error Codes

code message
103 Cannot void the delivery label. Details in error message.

Delivery Label Properties

label_id 
{ "label_id" : 2 }
The internal delivery label ID.
delivery_id 
{ "delivery_id" : 22 }
The internal delivery ID.
warehouse_id 
{ "warehouse_id" : 1 }
The internal warehouse ID.
status 
{ "status" : "valid" }
The "Status" property. Allowed: "valid", "void".
shipping_method 
{ "shipping_method" : "ups_03" }
See the Shipping Methods document for a reference. Is not optional.
created_at 
{ "created_at" : "2021-01-18T13:57:25+00:00" }
The "Created At" property in ISO 8601 format.
updated_at 
{ "updated_at" : "2021-01-18T13:57:25+00:00" }
The "Updated At" property in ISO 8601 format.
packages Array of delivery label packages. See Delivery Label Package Properties.
destination_address Destination Address. See Delivery Label Address Properties.
origin_address Origination Address. See Delivery Label Address Properties.
files An object with a label type as the key and the file data as the value. Allowed types: "label", "auxiliary_label", "customs_documents". See Delivery Label File Properties.

Delivery Label Package Properties

warehouse_id 
{ "warehouse_id" : "1" }
The ID of the warehouse associated with the package.
label_id 
{ "label_id" : 2 }
The internal delivery label ID.
carrier 
{ "carrier" : "ups" }
Carrier code.
weight 
{ "weight" : "16.900" }
The weight of the package.
weight_unit 
{ "weight_unit" : "lb" }
The unit of measure used for 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.
tracking 
[
    {
        "number" : "1Z49R7V80308849438",
        "description" : "UPS Ground"
    }, {
        "number" : "1Z49R7V29475663003",
        "description" : "UPS Ground"
    }
]
An array of tracking objects.
The "number" property contains the tracking number.
The "description" property contains the shipping method name.
package_items 
[
    {
        "delivery_item_id": 1,
        "sku": "product1",
        "quantity": "2.0000"
    }, {
        "delivery_item_id": 3,
        "sku": "product2",
        "quantity": "2.0000"
    }
]
An array of items contained in the package. 
"delivery_item_id" is the unqiue identifier of the related delivery item.
"sku" is the package item's SKU.
"quantity" is the quantity of the item in the package.

Delivery Label Address Properties

firstname 
{ "firstname" : "Gates" }
The "First Name" property.
lastname 
{ "lastname" : "Bill" }
The "Last Name" property.
company 
{ "company" : "Microsoft" }
The "Company" property.
street 
{ "street" : "11 Times Square\nc/oSteve Ballmer" }
The street address. Multi-line street addresses will be separated by a newline ("\n") character. Only two address lines are supported.
city 
{ "city" : "New York" }
The "City" property.
region 
{ "region" : "NY" }
The "Region" property.
postcode 
{ "postcode" : "10036" }
The "Postal Code" property. Pass as a string to prevent leading 0s from being dropped.
country 
{ "country" : "US" }
The "Country" property.
classification 
{ "classification" : "com" }
The "Classification" property. Allowed: "res" - residential, "com" - commercial, "po" - post office, "mil" - military, "unk" - unknown.
is_valid 
{ "is_valid" : 1 }
Flag whether address is valid.
telephone 
{ "telephone" : "212.245.2100" }
The "Telephone" property.
email 
{ "email" : "customer@example.com" }
The "Email" property.

Delivery Label Options

shipping_method 
{ "shipping_method" : "ups_03" }
See the Shipping Methods document for a reference. Is not optional.
return_service_type 
{ "return_service_type" : "print_or_download" }
The "Return Service Type" property. Allowed: "print_or_download", "email_label".
copy_email_to 
{ "copy_email_to" : "customer@example.com" }
The "Copy Email To" property. Comma separated emails. Only applicable to "email_label" Return Service Type.
email_message 
{ "email_message" : "Email message here." }
The "Email Notification Message" property. Only applicable to "email_label" Return Service Type.
saturday_pickup 
{ "saturday_pickup" : 1 }
The "Saturday Pickup" property.
declared_value_service 
{ "declared_value_service" : 1 }
The "Declared Value Service" property.
tpb_group_id 
{ "tpb_group_id" : 11 }
The ID number of a Third Party Billing Account Group. If unset or null, and a default group is configured, the default group will be used. Set to 0 to disable third party billing.

Delivery Label File Properties

type 
{ "type" : "pdf" }
The "Type" property. Allowed: "pdf".
data 
{ "data" : "bas64encoded..." }
Base64 encoded file content.