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

# Order

An order is a request from the merchant for an outbound shipment of the merchant's inventory. Each order is closely tracked through picking and packing all of the way to the time it is placed on the carrier's truck, even including which pallet the packages were loaded onto. When an order has begun picking it is split (if needed) into "Shipments" based on the most efficient way to meet carrier size and weight limitations. Each "shipment" therefore typically results in only one package although under some circumstances may still require more than one package.

## Methods

* [order.create](#order-create)
* [order.bulk\_create](#order-bulk-create)
* [order.edit](#order-edit)
* [order.search](#order-search)
* [order.info](#order-info)
* [order.hold](#order-hold)
* [order.unhold](#order-unhold)
* [order.cancel](#order-cancel)
* [order.comment](#order-comment)

## Entity Properties

* [Order Properties](#order-properties)
* [Order Item Properties](#order-item-properties)
* [Address Properties](#address-properties)
* [Package Properties](#package-properties)
* [Tracking Number Properties](#tracking-number-properties)
* [Status History](#status-history)
* [Serial Number Properties](#serial-number-properties)
* [Packing instruction Confirmation Properties](#packing-instruction-confirmation-properties)
* [Order Custom Field](#order-custom-field)

## Order States and Statuses

<ParamField path="new" type="string">
  Order received and inventory reserved.
  Valid statuses: `new`, `partial_backorder`, `backordered`
</ParamField>

<ParamField path="processing" type="string">
  Shipments created and assigned to a picking batch.
  Valid statuses: `processing`, `partial_backorder`
</ParamField>

<ParamField path="complete" type="string">
  Entire order has been packaged and labeled for shipping.
  Valid statuses: `complete`
</ParamField>

<ParamField path="canceled" type="string">
  Order has been canceled.
  Valid statuses: `canceled`
</ParamField>

<ParamField path="holded" type="string">
  Order is on hold.
  Valid statuses: `holded`, `delayed_shipment`, `unresolved`
</ParamField>

## `order.create`

`order.create (string|null $storeCode, object|array $items, object $address, object $info, object $flags = [])`

Create a new order. This operation will only be successful if the inventory is available and the unique\_id is unique (if specified).

### Parameters

<ParamField path="storeCode" type="string | null">
  Store code. If not specified will default to the configured default store. Merchants with multiple stores may specify which store the order belongs to.
</ParamField>

<ParamField path="items" type="object | array">
  Order Items. Three possible formats:

  ```json theme={null}
  { "product1's_SKU": 1, "product2's_SKU": 3 }
  ```

  ```json theme={null}
  [ { "sku": "product1", "qty": 1 }, { "sku": "product2", "qty": 3 } ]
  ```

  ```json theme={null}
  [ { "sku": "product1", "qty": 1, "unit_declared_value": "20.40", "unit_customs_value": "21.15" }, {...} ]
  ```
</ParamField>

<ParamField path="address" type="object">
  Shipping Address (see [Shipping Address Properties](#address-properties))
</ParamField>

<ParamField path="info" type="object">
  Order Additional Data (see [Order Additional Data](#order-additional-data))
</ParamField>

<ParamField path="flags" type="object">
  Order Flags (see [Order Flags](#order-flags))
</ParamField>

### Order Items Data

<ParamField path="sku" type="string">
  Use to specify the SKU of the item being ordered.
</ParamField>

<ParamField path="barcode" type="string">
  Use to specify the Barcode of the item being ordered as an alternative to using a SKU. The fields `sku`, `barcode`, and `vendor_sku` will be evaluated in that order, and the first matching product found will be selected.
</ParamField>

<ParamField path="vendor_sku" type="string">
  Use to specify the Vendor SKU of the item being ordered as an alternative to using a SKU or Barcode. The fields `sku`, `barcode`, and `vendor_sku` will be evaluated in that order, and the first matching product found will be selected. As Vendor SKUs are not unique, if the value matches multiple products then an error will be thrown.
</ParamField>

<ParamField path="qty" type="integer">
  Use to specify the quantity being ordered of a particular item.
</ParamField>

<ParamField path="order_item_ref" type="string">
  If required by your integration you may specify a reference to an external order item id.
</ParamField>

<ParamField path="unit_declared_value" type="string">
  Specify a declared unit value. Specifying the unit declared value is preferred over specifying only the entire order declared value so that an accurate amount can be computed for partial fulfillments. If a value is specified for an order item, then `"declared_value_service": true` will need to be sent in with the \$info object section.
</ParamField>

<ParamField path="unit_declared_value_currency" type="string">
  Specify the declared unit value currency. Must be a valid ISO 4217 alphabetic code.
</ParamField>

<ParamField path="unit_customs_value" type="string">
  Specify a customs unit value. Specifying the unit customs value is preferred over specifying only the entire order customs value so that an accurate amount can be computed for partial fulfillments.
</ParamField>

<ParamField path="unit_customs_value_currency" type="string">
  Specify the customs unit value currency. Must be a valid ISO 4217 alphabetic code.
</ParamField>

<ParamField path="inner_qty" type="integer">
  The number of eaches per inner container. Must be a positive whole number. If no BOM is found, individual units will be added.
</ParamField>

<ParamField path="outer_qty" type="integer">
  The number of inner containers, or number of eaches if there are no inner containers, per outer container. Must be a positive whole number. If no BOM is found, individual units will be added.
</ParamField>

### Order Additional Data

<ParamField path="unique_id" type="string">
  This field is optional and if not specified an auto-incrementing number will be assigned. Uniqueness based on this field is enforced so an error will be given if an order with the same unique\_id already exists. This 'unique\_id' is the id used for other API calls such as "order.info".
</ParamField>

<ParamField path="order_ref" type="string">
  This field is optional and if not specified will be left blank. Uniqueness based on this field is not enforced (two orders may have the same order\_ref value). If specified, this number will appear on packing slips in place of the unique\_id.
</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="custom_greeting" type="string">
  If specified will override the configured Packing Slip default greeting. Allowing the addition of a Packing Slip Custom Greeting.
</ParamField>

<ParamField path="note" type="string">
  The "Note" adds a status history to the order that only you and the warehouse staff may see. Adding a note will not affect the way the order is picked and packed and is not required.
</ParamField>

<ParamField path="signature_required" type="string">
  Values can be `none`, `any`, `adult`, `indirect`*, or `default`*.
  \*Supported by FedEx.

  * `none` — No signature requirement.
  * `any` — The package(s) will be shipped with the "Direct" signature required (recipient of any age).
  * `adult` — The package(s) will be shipped with the Adult Signature Required option (21 years or older).
  * `indirect` — The package(s) will be shipped with the `indirect` signature required (If `indirect` is not supported by the carrier, this option will fall back to `any`).
  * `default` — May be used to defer to the default based on the carrier service type (If `default` is not supported by the carrier, this option will fall back to `none`).
    If the signature requirement is not specified it will fall back to `default` for HazMat orders or `none` for all others.
</ParamField>

<ParamField path="saturday_delivery" type="boolean">
  Saturday delivery option. If not specified will default to 'false'.
</ParamField>

<ParamField path="reason_for_export" type="string">
  Reason for export. Values can be `sold`, `not_sold`, `gift`, `sample`, `repair_return`, `personal_effects`. If not specified will default to `sold`. Only applicable to international orders.
</ParamField>

<ParamField path="declared_value_service" type="boolean">
  If 'true' then the order or the package(s) will be shipped with declared\_value\_service requested. Only the unit\_declared\_value must be specified for at least one SKU or declared\_value for the order, but not both. If not specified will default to 'false'.
</ParamField>

<ParamField path="declared_value" type="string">
  Needs to be set if `"declared_value_service": true` and `"unit_declared_value"` is not set on any individual product SKU being ordered. e.g. `"declared_value": "40.50"`
</ParamField>

<ParamField path="declared_value_currency" type="string">
  The currency of `declared_value`. Must be a valid ISO 4217 alphabetic code.
</ParamField>

<ParamField path="customs_value" type="string">
  Only the unit\_customs\_value must be specified for at least one SKU or customs\_value for the order, but not both. e.g. `"customs_value": "30.25"`
</ParamField>

<ParamField path="customs_value_currency" type="string">
  The currency of `customs_value`. Must be a valid ISO 4217 alphabetic code.
</ParamField>

<ParamField path="overbox" type="boolean">
  Request overbox option. If not specified will default to 'false'.
</ParamField>

<ParamField path="backorder_policy" type="string">
  If specified, sets this order's backorder policy. Order will use specified policy instead of store's default policy. Values can be `default`, `all_or_nothing`, `as_available`, or `up_to_X`. If not specified will default to `"default"`.

  * `all_or_nothing` - Accept order but do not ship anything until all items are in stock.
  * `as_available` - No limit to number or frequency of additional shipments.
  * `up_to_X` shipments - Same as "As Available", but changes to All or Nothing before shipping Xth shipment.
    When using `up_to_X`, "X" represent a positive integer number. Example: ` { "backorder_policy": "up_to_3" }`
</ParamField>

<ParamField path="priority" type="integer">
  If specified, sets this order's priority. Setting the priority will boost or suppress this order's priority in relation to other orders for the same products. Valid input are values in the range `0 -100`. Lower numbers are higher in priority. If not specified will default to `50`.
</ParamField>

<ParamField path="requested_ship_date" type="string">
  If specified, the requested ship date will determine if the merchant wishes for the item to be shipped on the same day or not. Whether or not this date becomes the Target Ship Date depends on the merchant's target ship date cutoff time and the time the order is placed. Format: `YYYY-MM-DD`
</ParamField>

<ParamField path="desired_delivery_date" type="string">
  Required for the Cheapest On-Time shipping method. Format: `YYYY-MM-DD`
</ParamField>

<ParamField path="delayed_ship_date" type="string">
  If specified, the order will be placed in "hold" status until this date and time. May be specified as a date or a date and time. The timezone is assumed to be the global default timezone if not specified. If a time is not specified it is assumed to be 00:00:00 (12:00 am). Format: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ssZ`
</ParamField>

<ParamField path="hold_indefinitely" type="boolean">
  If specified, the order will be placed in "hold" status indefinitely (cannot be used with `delayed_ship_date`).
</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>

<ParamField path="duties_payor" type="string">
  Duties Payor. Values can be `default`, `shipper`, `recipient`, `third_party`. If not specified will default to `default`. Only applicable to international orders.
</ParamField>

<ParamField path="duties_tpb_group_id" type="integer">
  The ID number of a [Duties Payor Third Party Billing Account Group](/merchant-api/third-party-billing-group). Only applicable to `third_party` duties payor.
</ParamField>

<ParamField path="instructions" type="array">
  Array of packing instructions. See [Packing Instruction](#packing-instructions).
</ParamField>

<ParamField path="generate_sscc" type="array">
  Generate Serial Shipping Container Codes option. Array with elements 'pack' and/or 'item'. If not specified will default to an empty array.
</ParamField>

<ParamField path="custom_fields" type="object">
  Object with Custom Fields. See [Order Custom Field](#order-custom-field).
</ParamField>

### Order Flags

<ParamField path="unique_order_ref" type="boolean | string">
  Values can be `true`, `false`, a PHP strtotime string indicating the oldest date to consider. e.g. `-3 days`.

  * `true` — Must be unique across all orders.
  * `false` — Uniqueness is not required. (default - current behavior).
  * `-3 days` — Must be unique across all orders created for the last three days.
    If not specified it will fall back to `false`.
</ParamField>

### Return Value

An object with the new order's [Order Properties](#order-properties).

### Example Request

Create new order:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.create",
        [
            "mystorecode",
            [
                {
                    "sku": "product2",
                    "qty": 5,
                    "order_item_ref": "ref_12356-409821"
                }
            ],
            {
                "firstname" : "Davi",
                "lastname" : "Demir",
                "company" : "Demir Enterprises",
                "street1" : "11 Times Square",
                "city" : "New York",
                "region" : "NY",
                "postcode" : "10036",
                "country" : "US",
                "telephone" : "212.245.2100"
            },
            {
                "order_ref" : "12345",
                "shipping_method" : "ups_03",
                "custom_greeting" : "Greeting text here",
                "note" : "Note text here",
                "signature_required" : "none",
                "saturday_delivery" : false,
                "declared_value_service" : false,
                "overbox" : false,
                "delayed_ship_date" : "2022-07-28",
                "duties_payor" : "third_party",
                "duties_tpb_group_id" : "1",
                "custom_fields" : {"colors": [{"id" : 6}]}
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "order_id" : 117,
        "unique_id" : "100000017",
        ...
    }
}
```

### Error Codes

| code | message                                         |
| ---- | ----------------------------------------------- |
| 102  | Invalid data given. Details in error message.   |
| 104  | An order with the specified ID already exists.  |
| 106  | Invalid script given. Details in error message. |
| 107  | Product does not exist.                         |

***

## `order.bulk_create`

`order.bulk_create (object $orders)`

Create multiple new orders in a single request. This method is significantly faster than submitting orders one at a time. If an error occurs while processing an order, processing will continue with the next order.

### Parameters

<ParamField path="orders" type="object">
  An object with keys providing a reference for each order, which will be used in the response, and values which are an array of arguments as accepted by the [order.create](#ordercreate) endpoint.

  ```javascript theme={null}
  { 
      "mykey1": [ /* First order arguments */ ],
      "mykey2": [ /* Second order arguments */ ],
      "mykey3": [ /* Etc */ ]
  }
  ```
</ParamField>

### Return Value

An object with the new order's [Order Properties](#order-properties).

### Example Request

Create new orders:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        null,
        "order.bulk_create",
        [
            {
                "mykey1" : [
                    "mystorecode",
                    [
                        {
                            "sku": "product2",
                            "qty": 5,
                            "order_item_ref": "ref_12356-409821"
                        }
                    ],
                    {
                        "firstname" : "Davi",
                        "lastname" : "Demir",
                        "company" : "Demir Enterprises",
                        "street1" : "11 Times Square",
                        "city" : "New York",
                        "region" : "NY",
                        "postcode" : "10036",
                        "country" : "US",
                        "telephone" : "212.245.2100"
                    },
                    {
                        "order_ref" : "12345",
                        "shipping_method" : "ups_03",
                        "custom_greeting" : "Greeting text here",
                        "note" : "Note text here",
                        "signature_required" : "none",
                        "saturday_delivery" : false,
                        "declared_value_service" : false,
                        "overbox" : false,
                        "delayed_ship_date" : "2022-07-28",
                        "duties_payor" : "third_party",
                        "duties_tpb_group_id" : "1",
                        "custom_fields" : {"colors": [{"id" : 6}]}
                    }
                ],
                "mykey2" : [
                    "myotherstorecode",
                    [
                        {
                            "sku": "product1",
                            "qty": 5
                        }
                    ],
                    {
                        "firstname" : "John",
                        "lastname" : "Smith",
                        "street1" : "220 Pleasant Valley Way",
                        "city" : "West Orange",
                        "region" : "NJ",
                        "postcode" : "07052",
                        "country" : "US",
                        "telephone" : "212.290.3822"
                    },
                    {
                        "unique_id" : "12345",
                        "shipping_method" : "cheapest_ALL"
                    }
                ]
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "mykey1" : {
            "order_id" : 117,
            "unique_id" : "100000017",
            "order_ref" : null,
            "status" : "new"
        },
        "mykey2" : {
            "error" : {
                "code" : -32104,
                "message" : "An order with the specified ID already exists."
            }
        }
    }
}
```

### Error Codes

The error codes returned for specific orders are the same as those return by the [order.create](#error-codes) endpoint.

| code | message                                       |
| ---- | --------------------------------------------- |
| 102  | Invalid data given. Details in error message. |

***

## `order.edit`

`order.edit (string $orderUniqueId, object $address, object $info, object $customFields)`

Modify the Shipping Address and/or the Order Additional Data for the existing order.

### Parameters

<ParamField path="orderUniqueId" type="string | null">
  Order unique ID.
</ParamField>

<ParamField path="address" type="object">
  Shipping Address (see [Address Properties](#address-properties))
</ParamField>

<ParamField path="info" type="object">
  Order Additional Data (see [Order Additional Data](#order-additional-data))
</ParamField>

<ParamField path="customFields" type="object">
  Order Custom Field Operations (see [Order Custom Field Operations](#order-custom-field-operations))
</ParamField>

### Order Custom Field Operations

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

An object with the updated order's [Order Properties](#order-properties).

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.edit",
        [
            "100000309",
            {
                "firstname" : "Davi",
                "lastname" : "Demir"
            },
            {
                "shipping_method" : "ups_03"
            },
            {
                "add" : {
                    "cost_of_goods" : { "amount" : 100 },
                    "colors" : [ { "id" : 6 } ]
                }
            }
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "order_id" : 118,
        "unique_id" : "100000309",
        ...,
        "custom_fields" : {
            "cost_of_goods" : { "amount" : 100 },
            "colors" : [
                {
                    "id" : 12,
                    "label" : "Red"
                }
            ]
        }
    }
}
```

### Error Codes

| code | message                                       |
| ---- | --------------------------------------------- |
| 102  | Invalid data given. Details in error message. |
| 105  | The order cannot be edited.                   |

***

## `order.search`

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

Retrieve list of orders by filters. Order data can be customized by specifying properties to retrieve.

### Parameters

<ParamField path="filters" type="null | object">
  Filters to apply for the search.

  * `null` - Retrieve list of all orders.
  * `object` - Retrieve list of orders using specified [Search Filters](/merchant-api/search-filters).
</ParamField>

<ParamField path="options" type="null | object">
  Options to apply for the search.

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

<ParamField path="fields" type="null | string | object">
  Specify which fields should be included in the response.

  * `null` - Retrieve only "order\_id", "unique\_id", and "order\_ref" properties.
  * `string` - The string `'*'` denotes all properties **excluding** "shipping\_address", "items", "shipments", "tracking\_numbers", "packages", "status\_history", and "serial\_number\_data".
  * `object` - List of properties to retrieve in addition to "order\_id", "unique\_id", and "order\_ref". List may include '\*'.
    Example:

  ```json theme={null}
  ["*", "shipping_address"]
  ```

  See [Order Properties](#order-properties).
</ParamField>

### Return Value

An object containing:

* `results` - The matching records as an array of objects. Each object will contain the specified (or default if no fields parameter was given) [Order Properties](#order-properties).
* `totalCount` - The total number of records that match the query - this may be more than the number of records returned.
* `numPages` - The number of pages of records with the given page size.

### Example Request

Get order status and order items for two order ids:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.search",
        [
            {
                "order_id" : {
                    "in" : [
                        114,
                        115
                    ]
                }
            },
            null,
            [
                "status",
                "items"
            ]
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result": {
        "results" : [
            {
                "order_id" : 114,
                "unique_id" : "100000114",
                "order_ref" : null,
                "status" : "processing",
                "items" : [
                    {
                        "sku" : "product2",
                        "name" : "product2",
                        "qty_ordered": "1.0000",
                        "qty_backordered": "0.0000",
                        "qty_canceled": "0.0000",
                        "qty_processing": "0.0000",
                        "qty_shipped": "1.0000",
                        "unit_declared_value": null,
                        "unit_declared_value_currency": "USD",
                        "unit_customs_value": null,
                        "unit_customs_value_currency": "USD",
                        "weight": "5.800000",
                        "row_weight": "5.800000",
                        "package_data": [
                            { "label": "Serial Number - 8 Characters", "value": "12345ABC" }
                        ],
                        "allocation_data": [
                            { "warehouse_id": "2", "qty_allocated": "0.0000" }
                        ],
                        "order_item_id": "214",
                        "order_item_ref": null,
                        "weight_unit": "lb",
                        "row_weight_unit": "lb"
                    },
                    {
                        "sku" : "product1",
                        "name" : "product1",
                        "qty_ordered": "1.0000",
                        "qty_backordered": "0.0000",
                        "qty_canceled": "0.0000",
                        "qty_processing": "0.0000",
                        "qty_shipped": "0.0000",
                        "unit_declared_value": null,
                        "unit_declared_value_currency": "USD",
                        "unit_customs_value": null,
                        "unit_customs_value_currency": "USD",
                        "weight": "5.800000",
                        "row_weight": "5.800000",
                        "allocation_data": [
                            { "warehouse_id": "2", "qty_allocated": "1.0000" }
                        ],
                        "order_item_id": "215",
                        "order_item_ref": null,
                        "weight_unit": "lb",
                        "row_weight_unit": "lb"
                    }
                ]
            },
            {
                "order_id" : 115,
                "unique_id" : "100000116",
                "order_ref" : null,
                "status" : "backordered",
                "items" : [
                    {
                        "sku" : "product1",
                        "name" : "product1",
                        "qty_ordered": "2.0000",
                        "qty_backordered": "0.0000",
                        "qty_canceled": "0.0000",
                        "qty_processing": "0.0000",
                        "qty_shipped": "0.0000",
                        "unit_declared_value": null,
                        "unit_declared_value_currency": "USD",
                        "unit_customs_value": null,
                        "unit_customs_value_currency": "USD",
                        "weight": "5.800000",
                        "row_weight": "11.600000",
                        "allocation_data": [
                            { "warehouse_id": "2", "qty_allocated": "2.0000" }
                        ],
                        "order_item_id": "230",
                        "order_item_ref": null,
                        "weight_unit": "lb",
                        "row_weight_unit": "lb"
                    },
                    {
                        "sku" : "product3",
                        "name" : "product3",
                        "qty_ordered": "7.0000",
                        "qty_backordered": "1.0000",
                        "qty_canceled": "0.0000",
                        "qty_processing": "0.0000",
                        "qty_shipped": "0.0000",
                        "unit_declared_value": null,
                        "unit_declared_value_currency": "USD",
                        "unit_customs_value": null,
                        "unit_customs_value_currency": "USD",
                        "weight": "0.200000",
                        "row_weight": "1.400000",
                        "allocation_data": [
                            { "warehouse_id": "1", "qty_allocated": "2.0000" },
                            { "warehouse_id": "2", "qty_allocated": "4.0000" }
                        ],
                        "order_item_id": "232",
                        "order_item_ref": null,
                        "weight_unit": "lb",
                        "row_weight_unit": "lb"
                    }
                ]
            }
        ],
        "totalCount": 2,
        "numPages": 1
    },
    "jsonrpc" : 2.0,
    "id" : 1234
}
```

### Error Codes

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

***

## `order.info`

`order.info(string $orderUniqueId, null|string|object $fields = [])`

Retrieve full order information.

### Parameters

<ParamField path="orderUniqueId" type="string">
  Order unique ID.
</ParamField>

<ParamField path="fields" type="null | string | object">
  Specify which fields should be included in the response.

  * `null` - Retrieve only "order\_id", "unique\_id", and "order\_ref" properties.
  * `string` - The string `'*'` denotes all properties **excluding** "shipping\_address", "items", "shipments", "tracking\_numbers", and "status\_history".
  * `object` - List of properties to retrieve in addition to "order\_id", "unique\_id", and "order\_ref". List may include '\*'.
    Example:

  ```json theme={null}
  ["*", "shipping_address"]
  ```

  See [Order Properties](#order-properties).
</ParamField>

### Return Value

Object which contains the specified (or default if no fields parameter was given) [Order Properties](#order-properties).

### Example Request

Get order information for the specified order:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.info",
        [
            "100000114",
            [
                "status",
                "items"
            ]
        ]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "order_id" : 114,
        "unique_id" : "100000114",
        "order_ref" : null,
        "status" : "picking",
        "items" : [
            {
                "sku" : "product2",
                "name" : "product2",
                "weight" : 12.0000,
                "weight_unit" : "lb",
                "row_weight" : 12.0000,
                "row_weight_unit" : "lb",
                "qty_ordered" : 12.0000,
                "qty_processing" : 1.0000,
                "qty_shipped" : 0.0000,
                "qty_canceled" : 0.0000,
                "qty_backordered" : 11.0000,
                "package_data" : [
                    {"label" : "Serial Number - 8 Characters", "value" : "55285368"},
                    {"label" : "Serial Number - 8 Characters", "value" : "55285368"}
                ]
            },
            {
                "sku" : "product1",
                "name" : "product1",
                "weight" : 1.2300,
                "weight_unit" : "lb",
                "row_weight" : 1.2300,
                "row_weight_unit" : "lb",
                "qty_ordered" : 12.0000,
                "qty_processing" : 1.0000,
                "qty_shipped" : 0.0000,
                "qty_canceled" : 0.0000,
                "qty_backordered" : 11.0000,
                "package_data" : [
                    {"label" : "Serial Number - 8 Characters", "value" : "55285368"},
                    {"label" : "Serial Number - 8 Characters", "value" : "55285368"}
                ]
            }
        ]
    }
}
```

### Error Codes

| code | message                         |
| ---- | ------------------------------- |
| 100  | Requested order does not exist. |

***

## `order.hold`

`order.hold(string $orderUniqueId)`

Hold an existing order. This operation will only be successful if the order exists and can be holded.

### Parameters

<ParamField path="orderUniqueId" type="string">
  Order unique ID.
</ParamField>

### Return Value

`true` if the order was holded.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.hold",
        [
            "100000112"
        ]
    ]
}
```

### Example Response

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

### Error Codes

| code | message                                             |
| ---- | --------------------------------------------------- |
| 100  | Requested order does not exist.                     |
| 103  | Order status not changed. Details in error message. |

***

## `order.unhold`

`order.unhold(string $orderUniqueId)`

Unhold an existing order. This operation will only be successful if the order exists and can be unholded.

### Parameters

<ParamField path="orderUniqueId" type="string">
  Order unique ID.
</ParamField>

### Return Value

`true` if the order was unholded.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.unhold",
        [
            "100000112"
        ]
    ]
}
```

### Example Response

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

### Error Codes

| code | message                                             |
| ---- | --------------------------------------------------- |
| 100  | Requested order does not exist.                     |
| 103  | Order status not changed. Details in error message. |

***

## `order.cancel`

`order.cancel (string $uniqueOrderId, array $options, null|string|object $fields = [])`

Cancel an existing order. This operation will only be successful if the order exists, and at least one of the cancellation options is permitted for the order's current status and the store configuration.

### Parameters

<ParamField path="uniqueOrderId" type="string">
  Order unique ID
</ParamField>

<ParamField path="options" type="object">
  A list of the following properties, at least one of which must be set to `true`.

  * `backordered_items` - If the order has back ordered items, attempt to cancel them. If all items on the order are back ordered, then the entire order will be canceled.
  * `unfulfilled_items` - If the order has unfulfilled items, attempt to cancel them. If all items on the order are unfulfilled, then the entire order will be canceled. An unfulfilled item is an item that has not yet been added to a shipment for picking, including backordered items.
  * `all_items` - Attempt to cancel the entire order. If the order state is `processing` or `complete` then you will only be able to cancel the order if the store configuration allows it. If any items on the order have been fulfilled, then you must also set `cancellation_request` to `true`.
  * `cancellation_request` - If the `all_items` option is not available, you can use this option send a cancellation request instead.
    Example:

  ```json theme={null}
  {
      "backordered_items" : true,
      "unfulfilled_items" : false,
      "all_items" : false,
      "cancellation_request" : false
  }
  ```
</ParamField>

<ParamField path="fields" type="null | string | object">
  Specify which fields should be included in the order object returned in the response.

  * `null` - Retrieve only "order\_id", "unique\_id", and "order\_ref" properties.
  * `string` - The string `'*'` denotes all properties excluding "shipping\_address", "items", "tracking\_numbers" and "status\_history".
  * `object` - List of properties to retrieve in addition to "order\_id", "unique\_id", and "order\_ref". List may include '\*'.
    Example:

  ```json theme={null}
  ["*", "shipping_address"]
  ```

  See [Order Properties](#order-properties).
</ParamField>

### Return Value

An object containing the following properties:

* `success` - If at least one of the cancellation options was successful, the value will be `true`
* `warnings` - An array of warning messages
* `order` - Contains the specified (or default if no fields parameter was given) [Order Properties](#order-properties).

### Example Request

Attempt to cancel all items on an order:

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.cancel",
        [
            "100000114",
            {
                "all_items": true
            }
        ],
        ["status", "items"]
    ]
}
```

### Example Response

```json title="Response" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "success": false,
        "warnings": [
            "Order contains fulfilled items, please set the \"cancellation_request\" option to \"true\" and try again"
        ],
        "order": {
            "order_id" : 114,
            "unique_id" : "100000114",
            "order_ref" : null,
            "status" : "complete",
            "items" : [
                {
                    "sku" : "product2",
                    "name" : "product2",
                    "weight" : 12.0000,
                    "weight_unit" : "lb",
                    "row_weight" : 12.0000,
                    "row_weight_unit" : "lb",
                    "qty_ordered" : 12.0000,
                    "qty_processing" : 0.0000,
                    "qty_shipped" : 12.0000,
                    "qty_canceled" : 0.0000,
                    "qty_backordered" : 0.0000,
                    "package_data" : [
                        {"label" : "Serial Number - 8 Characters", "value" : "55285368"},
                        {"label" : "Serial Number - 8 Characters", "value" : "55285368"}
                    ],
                    "lot_data": [
                        {"lot_number": "83CCC2", "expiration_date": "2021-10-25", "origination_date": "2019-01-23", "qty": "12.0000"}
                    ]
                }
            ]
        }
    }
}
```

### Error Codes

| code | message                                             |
| ---- | --------------------------------------------------- |
| 100  | Requested order does not exist.                     |
| 102  | Invalid data given. Details in error message.       |
| 103  | Order status not changed. Details in error message. |

***

## `order.comment`

`order.comment(string $orderUniqueId, string $comment)`

Add a comment to an order's history.

*This method was added in version 2021.6.*

### Parameters

<ParamField path="orderUniqueId" type="string">
  Order unique ID.
</ParamField>

<ParamField path="comment" type="string">
  Comment.
</ParamField>

### Return Value

`true` if the comment was added.

### Example Request

```json title="Request" theme={null}
{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.comment",
        [
            "100000112",
            "Called customer and confirmed address."
        ]
    ]
}
```

### Example Response

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

### Error Codes

| code | message                                            |
| ---- | -------------------------------------------------- |
| 100  | Requested order does not exist.                    |
| 102  | Invalid data given. Details in error message.      |
| 103  | Order comment not added. Details in error message. |

***

## Entity Properties

### Order Properties

<Expandable title="Order Properties">
  <ParamField path="order_id" type="integer">
    The internal order ID.
  </ParamField>

  <ParamField path="unique_id" type="string">
    The unique id for the order. This will be auto-assigned if not specified by the merchant at order creation time. This "unique\_id" is the ID used for other API calls such as "order.info".
  </ParamField>

  <ParamField path="order_ref" type="string">
    An optional merchant-supplied reference for the order. Not a unique identifier.
  </ParamField>

  <ParamField path="state" type="string">
    State
  </ParamField>

  <ParamField path="status" type="string">
    Valid Order Statuses:

    | UI Label                   | Code                |
    | :------------------------- | :------------------ |
    | Backordered                | `backordered`       |
    | Canceled                   | `canceled`          |
    | Complete                   | `complete`          |
    | Scheduled Hold             | `delayed_shipment`  |
    | On Hold                    | `holded`            |
    | Invalid Address            | `invalid_address`   |
    | New                        | `new`               |
    | Partial Backorder          | `partial_backorder` |
    | Processing                 | `processing`        |
    | Unable To Process          | `unable_to_process` |
    | Unresolved Shipping Method | `unresolved`        |
  </ParamField>

  <ParamField path="store_code" type="string">
    Store Code
  </ParamField>

  <ParamField path="store_name" type="string">
    Store Name
  </ParamField>

  <ParamField path="carrier_code" type="string">
    Carrier Code
  </ParamField>

  <ParamField path="shipping_method" type="string">
    Shipping Description
  </ParamField>

  <ParamField path="shipping_description" type="string">
    Shipping Description
  </ParamField>

  <ParamField path="carrier_changed" type="boolean">
    Flag to identify whether carrier was changed.
  </ParamField>

  <ParamField path="is_address_modified" type="boolean">
    Flag to identify whether address was modified.
  </ParamField>

  <ParamField path="is_address_modified_auto" type="boolean">
    Flag to identify whether address was modified automatically.
  </ParamField>

  <ParamField path="weight" type="number">
    Weight
  </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="total_item_count" type="integer">
    Amount of order items.
  </ParamField>

  <ParamField path="remote_ip" type="string">
    Remote IP address used to submit the order
  </ParamField>

  <ParamField path="submitted_by" type="string">
    User-friendly description of method order was submitted.
  </ParamField>

  <ParamField path="submitted_by_type" type="string">
    Type of source used to submit the order (admin, client or api).
  </ParamField>

  <ParamField path="submitted_by_id" type="integer">
    The ID of the user that submitted the order.
  </ParamField>

  <ParamField path="signature_required" type="boolean">
    Flag to identify whether signature is required.
  </ParamField>

  <ParamField path="saturday_delivery" type="boolean">
    Flag to identify saturday delivery.
  </ParamField>

  <ParamField path="reason_for_export" type="string">
    Reason for export. Values can be `sold`, `not_sold`, `gift`, `sample`, `repair_return`, `personal_effects`. If not specified will default to `sold`. Only applicable to international orders.
  </ParamField>

  <ParamField path="overbox" type="boolean">
    Flag to identify overbox.
  </ParamField>

  <ParamField path="backorder_policy" type="string">
    This order's backorder policy. Order will use specified policy instead of store's default policy. Values can be `default`, `all_or_nothing`, `as_available`, or `up_to_X`. Default value is `default`.

    * `all_or_nothing` - Accept order but do not ship anything until all items are in stock.
    * `as_available` - No limit to number or frequency of additional shipments.
    * `up_to_X` shipments - Same as "As Available", but changes to All or Nothing before shipping Xth shipment.
      When using `up_to_X`, "X" represent a positive integer number. Example: ` { "backorder_policy": "up_to_3" }`
  </ParamField>

  <ParamField path="priority" type="integer">
    This order's priority. Setting the priority will boost or suppress this order's priority in relation to other orders for the same products. Valid input are values in the range `0 -100`. The default value is `50`. Lower numbers are higher in priority.
  </ParamField>

  <ParamField path="estimated_packages" type="integer">
    Estimated number of packages.
  </ParamField>

  <ParamField path="requested_ship_date" type="string">
    Date when the order was requested to be shipped.
  </ParamField>

  <ParamField path="custom_greeting" type="string">
    Custom greeting message if specified during order creation.
  </ParamField>

  <ParamField path="declared_value" type="number">
    Order declared value. Only the order declared value or order item unit declared value may be specified, but not both.
  </ParamField>

  <ParamField path="declared_value_currency" type="string">
    Order declared value currency. Must be a valid ISO 4217 alphabetic code.
  </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, then the default group will be used. Set to `0` to disable third party billing.
  </ParamField>

  <ParamField path="duties_payor" type="string">
    Duties Payor. Values can be `default`, `shipper`, `recipient`, `third_party`. If not specified will default to `default`. Only applicable to international orders.
  </ParamField>

  <ParamField path="duties_tpb_group_id" type="integer">
    The ID number of a [Duties Payor Third Party Billing Account Group](/merchant-api/third-party-billing-group). Only applicable to `third_party` duties payor.
  </ParamField>

  <ParamField path="created_at" type="string">
    Date and time when the order was created in ISO 8601 format.
  </ParamField>

  <ParamField path="updated_at" type="string">
    Date and time when the order was updated in ISO 8601 format.
  </ParamField>

  <ParamField path="completed_at" type="string">
    Date and time when the order was completed in ISO 8601 format.
  </ParamField>

  <ParamField path="shipped_at" type="string">
    Date and time when the order was completely shipped from the warehouse in ISO 8601 format.
  </ParamField>

  <ParamField path="delivered_at" type="string">
    Date and time when the order was completely delivered in ISO 8601 format.
  </ParamField>

  <ParamField path="shipping_address" type="object">
    The shipping address. See [Shipping Address Properties](#address-properties).
  </ParamField>

  <ParamField path="items" type="array">
    Array of order items. See [Order Item Properties](#order-item-properties).
  </ParamField>

  <ParamField path="shipments" type="array">
    Array of shipments. Only the "shipment\_id" and the "status" fields are present in the Order API. Use the [Shipment](/merchant-api/shipment) API to retrieve full shipment details.
  </ParamField>

  <ParamField path="tracking_numbers" type="array">
    Array of tracking numbers. See [Tracking Number Properties](#tracking-number-properties). *This property is deprecated - please use "packages" instead).*
  </ParamField>

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

  <ParamField path="status_history" type="array">
    Array of history statuses. See [Status History](#status-history).
  </ParamField>

  <ParamField path="serial_number_data" type="array">
    Array of serial numbers. See [Serial Number Properties](#serial-number-properties).
  </ParamField>
</Expandable>

### Packing Instructions

Packing Instructions are presented to the packer in a dialog that must be confirmed. If a file is attached, the file will be printed using the specified printer type the appropriate number of times depending on the "presentation". The file must be in PDF format, and for best results it is recommended for the paper size to match the printer target type. If the print target is a `LABEL` printer and the page size is not 4 inches in either dimension, the system will attempt to extract an image from the file or otherwise crop the page which may not always have good results.

<ParamField path="note" type="string">
  The "Note" property. This is required.
</ParamField>

<ParamField path="file_name" type="string">
  The name to be given to the file attached using the "file\_content" or "file\_request" properties.
</ParamField>

<ParamField path="file_content" type="string">
  The base64-encoded contents of the file. If specified you must also provide a "file\_name".
</ParamField>

<ParamField path="file_request" type="object">
  Attach a file using a url instead of `file_content`. The file will be downloaded using the optional `auth` and `headers` if specified. The `file_name` will be used if specified, but is optional and will otherwise be set using the `Content-Disposition` header value or the last part of the url.
</ParamField>

<ParamField path="presentation" type="string">
  The "Presentation" property. Values can be `once_per_order`, `once_per_shipment`, or `once_per_package`.
</ParamField>

<ParamField path="print_target" type="string">
  The "Print Target" property. Values can be `LABEL`, `SMALL_LABEL`, or `LASER`.
</ParamField>

<ParamField path="copies_printed" type="string">
  The "copies\_printed" property.
</ParamField>

<ParamField path="confirmations" type="array">
  The instruction confirmations. See [Packing instruction Confirmation Properties](#packing-instruction-confirmation-properties).
</ParamField>

#### Single Instruction Example:

```json theme={null}
"instructions": [
    {
        "note"         : "Place Amazon FBA Label in a pouch",
        "file_name"    : "amazon_fba_3425232.pdf",
        "file_content" : "base64-encoded file contents",
        "presentation" : "once_per_shipment",
        "print_target" : "LABEL",
        "copies_printed" : "1",
        "confirmations" : [
            {
                "confirmed_id" : "1",
                "confirmed_at": "2022-02-08T14:59:38+00:00"
            }
        ]
    }
]
```

#### Multiple Instructions example:

```json theme={null}
"instructions": [
    {
        "note"         : "Place Amazon FBA Label in a pouch",
        "file_name"    : "amazon_fba_3425232.pdf",
        "file_content" : "base64-encoded file contents",
        "presentation" : "once_per_shipment",
        "print_target" : "LABEL",
        "copies_printed" : "1",
        "confirmations" : [
            {
                "confirmed_id" : "1",
                "confirmed_at": "2022-02-08T14:59:38+00:00"
            }
        ]
    },
    {
        "note"         : "Place Flier in Package",
        "file_name"    : "flier_3425232.pdf",
        "file_request" : {
            "url": "https://....",
            "auth": ["username...","password..."],
            "headers": {
                "X-Custom-Header": "header value..."
            }
        },
        "presentation" : "once_per_package",
        "print_target" : "LASER",
        "copies_printed" : "1",
        "confirmations" : []
    }
]
```

#### Full `order.create` Example:

```json theme={null}
{
    "jsonrpc" : 2.0,
    "id"      : 1234,
    "method"  : "call",
    "params"  : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.create",
        [
            "rsf",
            [
                {
                    "sku": "product2",
                    "qty": 5,
                    "order_item_ref": "ref_12356-409821"
                }
            ],
            {
                "firstname" : "Davi",
                "lastname"  : "Demir",
                "company"   : "Demir Enterprises",
                "street1"   : "11 Times Square",
                "city"      : "New York",
                "region"    : "NY",
                "postcode"  : "10036",
                "country"   : "US",
                "telephone"     : "212.245.2100"
            },
            {
                "order_ref"              : "12345",
                "shipping_method"        : "ups_03",
                "custom_greeting"        : "Greeting text here",
                "note"                   : "Note text here",
                "signature_required"     : "none",
                "saturday_delivery"      : false,
                "declared_value_service" : false,
                "overbox"                : false,
                "requested_ship_date"    : "2014-07-28",
                "instructions"           : [
                     {
                        "note"         : "Place Amazon FBA Label in a pouch",
                        "file_name"    : "amazon_fba_3425232.pdf",
                        "file_content" : "base64-encoded file contents",
                        "presentation" : "once_per_shipment",
                        "print_target" : "LABEL"
                    },
                    {
                        "note"         : "Place extra padding between products and around edges.",
                        "presentation" : "once_per_package"
                    }
                ]
           }
        ]
    ]
}
```

### Order Item Properties

<Expandable title="Order Item Properties">
  <ParamField path="order_item_id" type="integer">
    The "Order Item ID" is a unique identifier for the order item.
  </ParamField>

  <ParamField path="order_item_ref" type="string">
    The "Order Item Ref" is an optional user-supplied value for the order item.
  </ParamField>

  <ParamField path="sku" type="string">
    The "SKU" property.
  </ParamField>

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

  <ParamField path="weight" type="number">
    The "Weight" property.
  </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="row_weight" type="number">
    Total order item weight.
  </ParamField>

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

  <ParamField path="qty_ordered" type="integer">
    Amount of ordered products.
  </ParamField>

  <ParamField path="qty_processing" type="integer">
    Amount of processing products.
  </ParamField>

  <ParamField path="qty_shipped" type="integer">
    Amount of shipped products.
  </ParamField>

  <ParamField path="qty_canceled" type="integer">
    Amount of canceled products.
  </ParamField>

  <ParamField path="qty_backordered" type="integer">
    Amount of backordered products.
  </ParamField>

  <ParamField path="allocation_data" type="array">
    The allocation quantity for each warehouse.
  </ParamField>

  <ParamField path="package_data" type="array">
    The "Package Data" property.
  </ParamField>

  <ParamField path="lot_data" type="array">
    The "Lot Data" property.
  </ParamField>
</Expandable>

### Address Properties

<Expandable title="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. If order is created with "1" the address verification will be skipped.
  </ParamField>

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

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

### Package Properties

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

  <ParamField path="status" type="string">
    The "Status" property. Allowed values: packing, tracking\_required, packed, manifested, shipped, delivered.
  </ParamField>

  <ParamField path="shipment_id" type="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.
  </ParamField>

  <ParamField path="shipment_status" type="string">
    The "Shipment Status" property. Allowed values: new, picking, picked, packing, packed, shipped, canceled, voided.
  </ParamField>

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

  <ParamField path="manifest_courier_code" type="string">
    Manifest courier code.
  </ParamField>

  <ParamField path="manifest_courier_name" type="string">
    Manifest courier name.
  </ParamField>

  <ParamField path="timestamp" type="string">
    The date and time when the package was created in ISO 8601 format.
  </ParamField>

  <ParamField path="shipped_at" type="string">
    Date and time when the package was shipped from the warehouse in ISO 8601 format.
  </ParamField>

  <ParamField path="delivered_at" type="string">
    Date and time when the package was delivered in ISO 8601 format.
  </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="billable_weight" type="integer">
    The billable weight of the package.
  </ParamField>

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

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

  <ParamField path="dimensional_weight_divisor_unit" type="string">
    The dimensional weight divisor unit. See: [Dimensional Divisor Units](/merchant-api/units-of-measure#dimensional-divisor).
  </ParamField>

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

  <ParamField path="rating_weight_unit" type="string">
    The unit of measure used for `dimensional_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="sscc" type="string">
    The Serial Shipping Container Code.
  </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. The "track\_url" property will contain a URL to the carrier's tracking page if applicable.
  </ParamField>

  <ParamField path="order_items" type="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.
  </ParamField>

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

  <ParamField path="package_data" type="array">
    The "Package Data" property.
  </ParamField>
</Expandable>

### Tracking Number Properties

*This entity is deprecated, please use [Package](#package-properties) instead.*

<Expandable title="Tracking Number Properties">
  <ParamField path="shipment_id" type="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.
  </ParamField>

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

  <ParamField path="carrier_name" type="string">
    The carrier name.
  </ParamField>

  <ParamField path="description" type="string">
    The method description (without the carrier name).
  </ParamField>

  <ParamField path="number" type="string">
    Tracking number.
  </ParamField>

  <ParamField path="date" type="string">
    The date and time when the shipping label was created in ISO 8601 format.
  </ParamField>

  <ParamField path="items" type="array">
    SKUs and quantities of the related package items.
  </ParamField>
</Expandable>

### Status History

<Expandable title="Status History">
  <ParamField path="status" type="string">
    The "Status" property.
  </ParamField>

  <ParamField path="comment" type="string">
    The "Comment" property.
  </ParamField>

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

### Serial Number Properties

<Expandable title="Serial Number Properties">
  <ParamField path="serial_id" type="string">
    The "Serial ID" property.
  </ParamField>

  <ParamField path="identifier" type="string">
    The unique identifier of the serial number.
  </ParamField>

  <ParamField path="sku" type="string">
    The SKU of the product associated with the serial number.
  </ParamField>

  <ParamField path="product_id" type="string">
    The ID of the product associated with the serial number.
  </ParamField>

  <ParamField path="package_id" type="string">
    The "Package ID" property. This will be `null` if this serial number was not packed yet.
  </ParamField>
</Expandable>

### Packing instruction Confirmation Properties

<Expandable title="Packing instruction Confirmation Properties">
  <ParamField path="confirmed_id" type="string">
    The ID of the instruction confirmation.
  </ParamField>

  <ParamField path="confirmed_at" type="string">
    Date and time when the instruction was confirmed in ISO 8601 format.
  </ParamField>
</Expandable>

### Order 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 [Order Custom Fields](/merchant-api/order-custom-field) — `order_custom_field.list`

<Expandable title="Order Custom Field">
  <ParamField path="text" type="object">
    Maximum number of characters is 1024.

    ```json theme={null}
    { "main_sku" : { "value" : "product2" } }
    ```
  </ParamField>

  <ParamField path="multiline-text" type="object">
    ```json theme={null}
    { "order_details" : { "value" : "Long multiline \n order details \n here." } }
    ```
  </ParamField>

  <ParamField path="number" type="object">
    ```json theme={null}
    { "number_of_skus" : { "value" : 5 } }
    ```

    ```json theme={null}
    { "length_and_girth" : { "value" : 54.25 } }
    ```
  </ParamField>

  <ParamField path="currency" type="object">
    ```json theme={null}
    { "cost_of_goods" : { "amount" : 105.95 } }
    ```
  </ParamField>

  <ParamField path="select" type="object">
    Select input type data must be an object with `label` or `id` key or both.

    ```json theme={null}
    { "claim_reason" : { "id" : 13 } }
    ```

    Preferred. An option is set by `id`.

    ```json theme={null}
    { "claim_reason" : { "label" : "Damaged in shipping" } }
    ```

    An option is set by `label`.

    ```json theme={null}
    { "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.
  </ParamField>

  <ParamField path="multiselect" type="array">
    Multi-select input type data must be an array of objects with `label` or `id` key or both.

    ```json theme={null}
    { "claim_reasons" : [ { "id" : 13 }, { "id" : 14 } ] }
    ```

    Preferred. An option is set by `id`.

    ```json theme={null}
    { "claim_reasons" : [ { "label" : "Damaged in shipping" }, { "label" : "Did not fit" } ] }
    ```

    An option is set by `label`.

    ```json theme={null}
    { "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.
  </ParamField>

  <ParamField path="boolean" type="object">
    ```json theme={null}
    { "allow_mailer" : { "value" : true } }
    ```
  </ParamField>

  <ParamField path="date" type="object">
    Must be in `Y-m-d` format.

    ```json theme={null}
    { "desired_delivery_date" : { "value" : "2023-01-23" } }
    ```
  </ParamField>

  <ParamField path="client-user" type="object">
    Must be a client user id.

    ```json theme={null}
    { "created_by" : { "value" : 5 } }
    ```
  </ParamField>

  <ParamField path="admin-user" type="object">
    Must be an admin user id.

    ```json theme={null}
    { "created_by" : { "value" : 7 } }
    ```
  </ParamField>

  <ParamField path="email" type="object">
    Must be a valid email address. Maximum number of characters is 1024.

    ```json theme={null}
    { "custom_email" : { "value" : "john.doe@example.com" } }
    ```
  </ParamField>

  <ParamField path="url" type="object">
    Must be a valid URL. Maximum number of characters is 1024.

    ```json theme={null}
    { "documentation_url" : { "value" : "https://example.com" } }
    ```
  </ParamField>
</Expandable>