> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Delivery Label

## Methods

* [delivery\_label.info](#delivery-label-info)
* [delivery\_label.search](#delivery-label-search)
* [delivery\_label.create](#delivery-label-create)
* [delivery\_label.void](#delivery-label-void)

***

## Entity Properties

* [Delivery Label](#delivery-label-properties)
* [Delivery Label Package](#delivery-label-package-properties)
* [Delivery Label Address](#delivery-label-address-properties)

***

## `delivery_label.info`

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

Retrieve delivery label information.

### Parameters

<ParamField path="labelId" type="integer">
  Delivery label internal id
</ParamField>

<ParamField path="fields" type="array">
  * `null` - Basic label data.
  * `array` - Array of fields. Allowed: "packages", "destination\_address", "origin\_address"
</ParamField>

### Return Value

An object with [Delivery Label Properties](#delivery-label-properties).

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "12e6f7398eb7a992219477aaa771725d",
        "delivery_label.info",
        [
            "2",
            [
                "packages",
                "destination_address",
                "origin_address",
                "files"
            ]
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "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`

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

An array of objects. Each object will contain [Delivery Label Properties](#delivery-label-properties).

### Parameters

<ParamField path="filters" type="object | null">
  * `null` - Retrieve list of all delivery labels.
  * `object` - Retrieve list of delivery labels using specified [Search Filters](/merchant-api/search-filters).
</ParamField>

<ParamField path="options" type="array | null">
  * `null` - No options will be applied.
  * `object` - Apply specified [Search Options](/merchant-api/search-options).
</ParamField>

<ParamField path="fields" type="array | null">
  * `null` - Basic label data.
  * `array` - Array of fields. Allowed: "packages", "destination\_address", "origin\_address"
</ParamField>

### Return Value

An array of objects. Each object will contain [Delivery Label Properties](#delivery-label-properties).

### Example Request

```json title="Request" theme={null}
{
    "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

```json title="Response" theme={null}
{
    "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`

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

Create a new delivery label.

### Parameters

<ParamField path="incrementId" type="string">
  Delivery # (i.e., the ASN # or RMA # depending on the type)
</ParamField>

<ParamField path="address" type="object">
  Destination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
</ParamField>

<ParamField path="packages" type="array">
  Array of delivery label packages. See [Delivery Label Package Properties](#delivery-label-package-properties).
</ParamField>

<ParamField path="options" type="object">
  Options. See [Delivery Label Options](#delivery-label-options).
</ParamField>

### Return Value

An object with [Delivery Label Properties](#delivery-label-properties).

### Example Request

```json title="Request" theme={null}
{
    "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

```json title="Response" theme={null}
{
    "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`

`delivery_label.void (int $labelId)`

Void delivery label.

### Parameters

<ParamField path="labelId" type="integer">
  Delivery label internal id
</ParamField>

### Return Value

`true` if the Delivery Label was voided.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "12e6f7398eb7a992219477aaa771725d",
        "delivery_label.void",
        [
            "8"
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "result": true
}
```

### Error Codes

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

## Entity Properties

### Delivery Label Properties

<Expandable title="Delivery Label Properties">
  <ParamField path="label_id" type="integer">
    The internal delivery label ID.
  </ParamField>

  <ParamField path="delivery_id" type="integer">
    The internal delivery ID.
  </ParamField>

  <ParamField path="warehouse_id" type="integer">
    The internal warehouse ID.
  </ParamField>

  <ParamField path="status" type="string">
    The "Status" property. Allowed: "valid", "void".
  </ParamField>

  <ParamField path="shipping_method" type="string">
    See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference. Is not optional.
  </ParamField>

  <ParamField path="created_at" type="string">
    The "Created At" property in ISO 8601 format.
  </ParamField>

  <ParamField path="updated_at" type="string">
    The "Updated At" property in ISO 8601 format.
  </ParamField>

  <ParamField path="packages" type="array">
    Array of delivery label packages. See [Delivery Label Package Properties](#delivery-label-package-properties).
  </ParamField>

  <ParamField path="destination_address" type="object">
    Destination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
  </ParamField>

  <ParamField path="origin_address" type="object">
    Origination Address. See [Delivery Label Address Properties](#delivery-label-address-properties).
  </ParamField>

  <ParamField path="files" type="object">
    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-file-properties).
  </ParamField>
</Expandable>

### Delivery Label Package Properties

<Expandable title="Delivery Label Package Properties">
  <ParamField path="warehouse_id" type="string">
    The ID of the warehouse associated with the package.
  </ParamField>

  <ParamField path="label_id" type="integer">
    The internal delivery label ID.
  </ParamField>

  <ParamField path="carrier" type="string">
    Carrier code.
  </ParamField>

  <ParamField path="weight" type="string">
    The weight of the package.
  </ParamField>

  <ParamField path="weight_unit" type="string">
    The unit of measure used for `weight`. See: [Weight Units](/merchant-api/units-of-measure#weight).
  </ParamField>

  <ParamField path="dimensions" type="object">
    The `length`, `width`, and `height` of the package.
  </ParamField>

  <ParamField path="dimension_unit" type="string">
    The unit of measure used for `length`, `width`, and `height` in `dimensions`. See: [Length Units](/merchant-api/units-of-measure#length).
  </ParamField>

  <ParamField path="tracking" type="array">
    An array of tracking objects. The "number" property contains the tracking number. The "description" property contains the shipping method name.
  </ParamField>

  <ParamField path="package_items" type="array">
    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.
  </ParamField>
</Expandable>

### Delivery Label Address Properties

<Expandable title="Delivery Label Address Properties">
  <ParamField path="firstname" type="string">
    The "First Name" property.
  </ParamField>

  <ParamField path="lastname" type="string">
    The "Last Name" property.
  </ParamField>

  <ParamField path="company" type="string">
    The "Company" property.
  </ParamField>

  <ParamField path="street" type="string">
    The street address. Multi-line street addresses will be separated by a newline ("\n") character. Only two address lines are supported.
  </ParamField>

  <ParamField path="city" type="string">
    The "City" property.
  </ParamField>

  <ParamField path="region" type="string">
    The "Region" property.
  </ParamField>

  <ParamField path="postcode" type="string">
    The "Postal Code" property. Pass as a string to prevent leading 0s from being dropped.
  </ParamField>

  <ParamField path="country" type="string">
    The "Country" property.
  </ParamField>

  <ParamField path="classification" type="string">
    The "Classification" property. Allowed: "res" - residential, "com" - commercial, "po" - post office, "mil" - military, "unk" - unknown.
  </ParamField>

  <ParamField path="is_valid" type="integer">
    Flag whether address is valid.
  </ParamField>

  <ParamField path="telephone" type="string">
    The "Telephone" property.
  </ParamField>

  <ParamField path="email" type="string">
    The "Email" property.
  </ParamField>
</Expandable>

### Delivery Label Options

<Expandable title="Delivery Label Options">
  <ParamField path="shipping_method" type="string">
    One or more shipping methods. See the [Shipping Methods](/merchant-api/shipping-methods) document for a reference.
  </ParamField>

  <ParamField path="return_service_type" type="string">
    The "Return Service Type" property. Allowed: "print\_or\_download", "email\_label".
  </ParamField>

  <ParamField path="copy_email_to" type="string">
    The "Copy Email To" property. Comma separated emails. Only applicable to "email\_label" Return Service Type.
  </ParamField>

  <ParamField path="email_message" type="string">
    The "Email Notification Message" property. Only applicable to "email\_label" Return Service Type.
  </ParamField>

  <ParamField path="saturday_pickup" type="integer">
    The "Saturday Pickup" property.
  </ParamField>

  <ParamField path="declared_value_service" type="integer">
    The "Declared Value Service" property.
  </ParamField>

  <ParamField path="tpb_group_id" type="integer">
    The ID number of a [Third Party Billing Account Group](/merchant-api/third-party-billing-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.
  </ParamField>
</Expandable>

### Delivery Label File Properties

<Expandable title="Delivery Label File Properties">
  <ParamField path="type" type="string">
    The "Type" property. Allowed: "pdf".
  </ParamField>

  <ParamField path="data" type="string">
    Base64 encoded file content.
  </ParamField>
</Expandable>