Order - ShipStream Developer Center

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.

Entity Properties

Order Properties
Order Item Properties
Address Properties
Package Properties
Tracking Number Properties
Status History
Serial Number Properties
Packing instruction Confirmation Properties
Order Custom Field

Order States and Statuses

string

Order received and inventory reserved. Valid statuses: new, partial_backorder, backordered

string

Shipments created and assigned to a picking batch. Valid statuses: processing, partial_backorder

string

Entire order has been packaged and labeled for shipping. Valid statuses: complete

string

Order has been canceled. Valid statuses: canceled

string

Order is on hold. Valid statuses: holded, delayed_shipment, unresolved

`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

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.

object | array

Order Items. Three possible formats:

{ "product1's_SKU": 1, "product2's_SKU": 3 }

[ { "sku": "product1", "qty": 1 }, { "sku": "product2", "qty": 3 } ]

[ { "sku": "product1", "qty": 1, "unit_declared_value": "20.40", "unit_customs_value": "21.15" }, {...} ]

object

Shipping Address (see Shipping Address Properties)

object

Order Additional Data (see Order Additional Data)

object

Order Flags (see Order Flags)

Order Items Data

string

Use to specify the SKU of the item being ordered.

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.

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.

integer

Use to specify the quantity being ordered of a particular item.

string

If required by your integration you may specify a reference to an external order item id.

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.

string

Specify the declared unit value currency. Must be a valid ISO 4217 alphabetic code.

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.

string

Specify the customs unit value currency. Must be a valid ISO 4217 alphabetic code.

integer

The number of eaches per inner container. Must be a positive whole number. If no BOM is found, individual units will be added.

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.

Order Additional Data

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

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.

string

See the Shipping Methods document for a reference. Is not optional.

string

If specified will override the configured Packing Slip default greeting. Allowing the addition of a Packing Slip Custom Greeting.

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.

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.

boolean

Saturday delivery option. If not specified will default to ‘false’.

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.

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

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"

string

The currency of declared_value. Must be a valid ISO 4217 alphabetic code.

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"

string

The currency of customs_value. Must be a valid ISO 4217 alphabetic code.

boolean

Request overbox option. If not specified will default to ‘false’.

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

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.

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

string

Required for the Cheapest On-Time shipping method. Format: YYYY-MM-DD

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

boolean

If specified, the order will be placed in “hold” status indefinitely (cannot be used with delayed_ship_date).

integer

The ID number of a Third Party Billing Account Group. If unset or null, and a default group is configured, the default group will be used. Set to 0 to disable third party billing.

string

Duties Payor. Values can be default, shipper, recipient, third_party. If not specified will default to default. Only applicable to international orders.

integer

The ID number of a Duties Payor Third Party Billing Account Group. Only applicable to third_party duties payor.

array

Array of packing instructions. See Packing Instruction.

array

Generate Serial Shipping Container Codes option. Array with elements ‘pack’ and/or ‘item’. If not specified will default to an empty array.

object

Object with Custom Fields. See Order Custom Field.

string

Links the order to a Retailer by its code. When set, the retailer’s configured order defaults (duties payor, third-party-billing groups, shipping method) fill any of those fields left unset.

object

Identifies the retailer ship-to location this order is destined for by its (qualifier, code) pair. Requires retailer_code. On a match the existing location is linked. On a miss, a drop_ship/mixed retailer proceeds with no link, while a wholesale retailer either auto-creates the location (when the retailer_ship_to_location_create flag is set) or is rejected.

Show Retailer Ship-To Location Reference

string

required

The ship-to location code.

string

required

The canonical qualifier scheme for the code (for example gln or buyer_location). See the Retailer Ship-To Location allowed values.

string

Optional display label applied when a location is auto-created.

string

Optional location type applied when a location is auto-created. Allowed values: dc, store, drop_ship, other.

Order Flags

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.

boolean

When true, a wholesale retailer’s retailer_ship_to_location that does not match an existing location is created from the order’s shipping address inside the order transaction and linked. When false (default), an unmatched wholesale ship-to is rejected. Only applies to wholesale retailers.

Return Value

An object with the new order’s Order Properties.

Example Request

Create new order:

Request

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

Response

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

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

{ 
    "mykey1": [ /* First order arguments */ ],
    "mykey2": [ /* Second order arguments */ ],
    "mykey3": [ /* Etc */ ]
}

Return Value

An object with the new order’s Order Properties.

Example Request

Create new orders:

Request

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

Response

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

string | null

Order unique ID.

object

Shipping Address (see Address Properties)

object

Order Additional Data (see Order Additional Data)

object

Order Custom Field Operations (see Order Custom Field Operations)

Order Custom Field Operations

An object with an operation name as the key and an object containing the 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.

Example Request

Request

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

Response

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

null | object

Filters to apply for the search.

null - Retrieve list of all orders.
object - Retrieve list of orders using specified Search Filters.

null | object

Options to apply for the search.

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

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:

["*", "shipping_address"]

See Order Properties.

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

Request

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

Example Response

Response

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

string

Order unique ID.

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:

["*", "shipping_address"]

See Order Properties.

Return Value

Object which contains the specified (or default if no fields parameter was given) Order Properties.

Example Request

Get order information for the specified order:

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.info",
        [
            "100000114",
            [
                "status",
                "items"
            ]
        ]
    ]
}

Example Response

Response

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

string

Order unique ID.

Return Value

true if the order was holded.

Example Request

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.hold",
        [
            "100000112"
        ]
    ]
}

Example Response

Response

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

string

Order unique ID.

Return Value

true if the order was unholded.

Example Request

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.unhold",
        [
            "100000112"
        ]
    ]
}

Example Response

Response

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

string

Order unique ID

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:

{
    "backordered_items" : true,
    "unfulfilled_items" : false,
    "all_items" : false,
    "cancellation_request" : false
}

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:

["*", "shipping_address"]

See Order Properties.

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.

Example Request

Attempt to cancel all items on an order:

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.cancel",
        [
            "100000114",
            {
                "all_items": true
            }
        ],
        ["status", "items"]
    ]
}

Example Response

Response

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

string

Order unique ID.

string

Comment.

Return Value

true if the comment was added.

Example Request

Request

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "method" : "call",
    "params" : [
        "be1c13ed4e03f0ed7f1e4053dfff9658",
        "order.comment",
        [
            "100000112",
            "Called customer and confirmed address."
        ]
    ]
}

Example Response

Response

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

Show Order Properties

integer

The internal order ID.

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

string

An optional merchant-supplied reference for the order. Not a unique identifier.

string

State

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`

string

Store Code

string

Store Name

string

Carrier Code

string

Shipping Description

string

Shipping Description

boolean

Flag to identify whether carrier was changed.

boolean

Flag to identify whether address was modified.

boolean

Flag to identify whether address was modified automatically.

number

Weight

string

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

integer

Amount of order items.

string

Remote IP address used to submit the order

string

User-friendly description of method order was submitted.

string

Type of source used to submit the order (admin, client or api).

integer

The ID of the user that submitted the order.

boolean

Flag to identify whether signature is required.

boolean

Flag to identify saturday delivery.

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.

boolean

Flag to identify overbox.

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

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.

integer

Estimated number of packages.

string

Date when the order was requested to be shipped.

string

Custom greeting message if specified during order creation.

number

Order declared value. Only the order declared value or order item unit declared value may be specified, but not both.

string

Order declared value currency. Must be a valid ISO 4217 alphabetic code.

integer

The ID number of a Third Party Billing Account 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.

string

Duties Payor. Values can be default, shipper, recipient, third_party. If not specified will default to default. Only applicable to international orders.

integer

The ID number of a Duties Payor Third Party Billing Account Group. Only applicable to third_party duties payor.

integer

The internal ID of the linked B2B Retailer, or null. Makes the link visible without loading the retailer.

object

The linked Retailer, or null. Excluded from order.search results by default; request it explicitly via the fields parameter.

Show Retailer

integer

The internal retailer ID.

string

The retailer code.

string

The retailer name.

integer

The internal ID of the linked Retailer Ship-To Location, or null. Makes the link visible without loading the location.

object

The linked retailer ship-to location, or null. Excluded from order.search results by default; request it explicitly via the fields parameter.

Show Retailer Ship-To Location

integer

The internal ship-to location ID.

string

The canonical qualifier scheme for the code. See the Retailer Ship-To Location allowed values.

string

The ship-to location code.

string

Optional display label.

string

Location type. One of dc, store, drop_ship, other.

string

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

string

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

string

Date and time when the order was completed in ISO 8601 format.

string

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

string

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

object

The shipping address. See Shipping Address Properties.

array

Array of order items. See Order Item Properties.

array

Array of shipments. Only the “shipment_id” and the “status” fields are present in the Order API. Use the Shipment API to retrieve full shipment details.

array

Array of tracking numbers. See Tracking Number Properties. This property is deprecated - please use “packages” instead).

array

Array of packages. See Package Properties.

array

Array of history statuses. See Status History.

array

Array of serial numbers. See Serial Number Properties.

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.

string

The “Note” property. This is required.

string

The name to be given to the file attached using the “file_content” or “file_request” properties.

string

The base64-encoded contents of the file. If specified you must also provide a “file_name”.

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.

string

The “Presentation” property. Values can be once_per_order, once_per_shipment, or once_per_package.

string

The “Print Target” property. Values can be LABEL, SMALL_LABEL, or LASER.

string

The “copies_printed” property.

array

The instruction confirmations. See Packing instruction Confirmation Properties.

Single Instruction Example:

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

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

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

Show Order Item Properties

integer

The “Order Item ID” is a unique identifier for the order item.

string

The “Order Item Ref” is an optional user-supplied value for the order item.

string

The “SKU” property.

string

The “Name” property.

number

The “Weight” property.

string

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

number

Total order item weight.

string

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

integer

Amount of ordered products.

integer

Amount of processing products.

integer

Amount of shipped products.

integer

Amount of canceled products.

integer

Amount of backordered products.

array

The allocation quantity for each warehouse.

array

The “Package Data” property.

array

The “Lot Data” property.

Address Properties

Show Address Properties

string

The “First Name” property.

string

The “Last Name” property.

string

The “Company” property.

string

The street address. Multi-line street addresses will be separated by a newline (“\n”) character. Only two address lines are supported.

string

The “City” property.

string

The “Region” property.

string

The “Postal Code” property. Pass as a string to prevent leading 0s from being dropped.

string

The “Country” property.

string

The “Classification” property. Allowed: “res” - residential, “com” - commercial, “po” - post office, “mil” - military, “unk” - unknown.

integer

Flag whether address is valid. If order is created with “1” the address verification will be skipped.

string

The “Telephone” property.

string

The “Email” property.

Package Properties

Show Package Properties

string

The ID of the warehouse associated with the package.

string

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

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.

string

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

string

Carrier code.

string

Manifest courier code.

string

Manifest courier name.

string

The date and time when the package was created in ISO 8601 format.

string

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

string

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

string

The weight of the package.

string

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

integer

The billable weight of the package.

string

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

string

The dimensional weight divisor of the package.

string

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

string

The dimensional weight of the package.

string

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

object

The length, width, and height of the package.

string

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

string

The Serial Shipping Container Code.

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.

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.

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.

array

The “Package Data” property.

Tracking Number Properties

This entity is deprecated, please use Package instead.

Show Tracking Number Properties

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.

string

Carrier code.

string

The carrier name.

string

The method description (without the carrier name).

string

Tracking number.

string

The date and time when the shipping label was created in ISO 8601 format.

array

SKUs and quantities of the related package items.

Status History

Show Status History

string

The “Status” property.

string

The “Comment” property.

string

The “Created At” property in ISO 8601 format.

Serial Number Properties

Show Serial Number Properties

string

The “Serial ID” property.

string

The unique identifier of the serial number.

string

The SKU of the product associated with the serial number.

string

The ID of the product associated with the serial number.

string

The “Package ID” property. This will be null if this serial number was not packed yet.

Packing instruction Confirmation Properties

Show Packing instruction Confirmation Properties

string

The ID of the instruction confirmation.

string

Date and time when the instruction was confirmed in ISO 8601 format.

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 — order_custom_field.list

Show Order Custom Field

object

Maximum number of characters is 1024.

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

object

{ "order_details" : { "value" : "Long multiline \n order details \n here." } }

object

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

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

object

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

object

Select input type data must be an object with label or id key or both.

{ "claim_reason" : { "id" : 13 } }

Preferred. An option is set by id.

{ "claim_reason" : { "label" : "Damaged in shipping" } }

An option is set by label.

{ "claim_reason" : { "id" : 13, "label" : "Damaged in shipping" } }

An option is set by id and label. The id and the label must refer to the same option.

array

Multi-select input type data must be an array of objects with label or id key or both.

{ "claim_reasons" : [ { "id" : 13 }, { "id" : 14 } ] }

Preferred. An option is set by id.

{ "claim_reasons" : [ { "label" : "Damaged in shipping" }, { "label" : "Did not fit" } ] }

An option is set by label.

{ "claim_reasons" : [ { "id" : 13, "label" : "Damaged in shipping" }, { "id" : 14, "label" : "Did not fit" } ] }

An option is set by id and label. The id and the label must refer to the same option.

object

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

object

Must be in Y-m-d format.

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

object

Must be a client user id.

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

object

Must be an admin user id.

{ "created_by" : { "value" : 7 } }

object

Must be a valid email address. Maximum number of characters is 1024.

{ "custom_email" : { "value" : "john.doe@example.com" } }

object

Must be a valid URL. Maximum number of characters is 1024.

{ "documentation_url" : { "value" : "https://example.com" } }

​Methods

​Entity Properties

​Order States and Statuses

​order.create

​Parameters

​Order Items Data

​Order Additional Data

​Order Flags

​Return Value

​Example Request

​Example Response

​Error Codes

​order.bulk_create

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​order.edit

​Parameters

​Order Custom Field Operations

​Return Value

​Example Request

​Example Response

​Error Codes

​order.search

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​order.info

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​order.hold

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​order.unhold

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​order.cancel

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​order.comment

​Parameters

​Return Value

​Example Request

​Example Response

​Error Codes

​Entity Properties

​Order Properties

​Packing Instructions

​Single Instruction Example:

​Multiple Instructions example:

​Full order.create Example:

​Order Item Properties

​Address Properties

​Package Properties

​Tracking Number Properties

​Status History

​Serial Number Properties

​Packing instruction Confirmation Properties

​Order Custom Field

Methods

Entity Properties

Order States and Statuses

`order.create`

Parameters

Order Items Data

Order Additional Data

Order Flags

Return Value

Example Request

Example Response

Error Codes

`order.bulk_create`

Parameters

Return Value

Example Request

Example Response

Error Codes

`order.edit`

Parameters

Order Custom Field Operations

Return Value

Example Request

Example Response

Error Codes

`order.search`

Parameters

Return Value

Example Request

Example Response

Error Codes

`order.info`

Parameters

Return Value

Example Request

Example Response

Error Codes

`order.hold`

Parameters

Return Value

Example Request

Example Response

Error Codes

`order.unhold`

Parameters

Return Value

Example Request

Example Response

Error Codes

`order.cancel`

Parameters

Return Value

Example Request

Example Response

Error Codes

`order.comment`

Parameters

Return Value

Example Request

Example Response

Error Codes

Entity Properties

Order Properties

Packing Instructions

Single Instruction Example:

Multiple Instructions example:

Full `order.create` Example:

Order Item Properties

Address Properties

Package Properties

Tracking Number Properties

Status History

Serial Number Properties

Packing instruction Confirmation Properties

Order Custom Field