Get integrated with ShipStream!

• Home
• Documentation
• API Basics
• Units of Measure
• Search Filters
• Search Options
• Shipping Methods
• Import Formats
• API Reference
• Stock Movements
• Enumerations
• Third Party Billing
• Bill of Materials
• Rate
• Log
• Warehouse
• Import
• Webhook
• Topics
• Store
• Delivery
• Delivery Label
• Product
• Media
• Shipment
• Package
• Order
• Custom Fields
• Packing Instructions
• State Data
• Inventory

Methods

• order.create
• order.bulk_create
• order.edit
• order.search
• order.info
• order.hold
• order.unhold
• order.cancel
• order.comment

Entity Properties

• Order
• Order Item
• Packing Instructions
• Packing Instruction Confirmation
• Shipping Address
• Tracking Number (deprecated - please use Package instead)
• Package
• Status History
• Order Custom Field

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.

Order States and Statuses

new

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

processing

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

complete

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

canceled

Order has been canceled. Valid statuses: canceled

holded

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

order.create

order.create (string|null $storeCode, object $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

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

1 object

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" }, {...} ]

2 object

Shipping Address (see “Shipping Address Properties”)

3 object

Order Additional Data (see “Order Additional Data”)

4 object

Order Flags (see “Order Flags”)

Order Items Data

sku

Use to specify the SKU of the item being ordered.

barcode

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.

vendor_sku

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.

qty

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

order_item_ref

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

unit_declared_value

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.

unit_declared_value_currency

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

unit_customs_value

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.

unit_customs_value_currency

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

inner_qty

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

outer_qty

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

unique_id

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

order_ref

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.

shipping_method

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

custom_greeting

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

note

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.

signature_required

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.

saturday_delivery

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

reason_for_export

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.

declared_value_service

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

declared_value

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"

declared_value_currency

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

customs_value

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"

customs_value_currency

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

overbox

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

backorder_policy

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

priority

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.

requested_ship_date

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

desired_delivery_date

Required for the Cheapest On-Time shipping method.

Format: YYYY-MM-DD

delayed_ship_date

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

hold_indefinitely

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

tpb_group_id

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.

duties_payor

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

duties_tpb_group_id

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

instructions

Array of packing instructions. See “Packing Instruction”.

generate_sscc

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

custom_fields

Object with Custom Fields. See Order Custom Field.

Order Flags

unique_order_ref

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.

Return Value

An object with the new order’s Order Properties.

Example Request

Create new order:

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

{
    "jsonrpc" : 2.0,
    "id" : 1234,
    "error" : null,
    "result" : {
        "order_id" : 117,
        "unique_id" : "100000017",
        ...
    }
}

Error Codes

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

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

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

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

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

0 string|null

Order unique ID.

1 object

Shipping Address (see “Address Properties”)

2 object

Order Additional Data (see “Order Additional Data”)

3 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

{
    "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" : [ { "label" : "Red" } ]
                }
            }
        ]
    ]
}

Example 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

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

0 null|object

Filters to apply for the search.

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

1 null|object

Options to apply for the search.

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

2 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”, 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:

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

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

Example 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

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

Retrieve full order information.

Parameters

0 string

Order unique ID.

1 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”, 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:

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

Example 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

order.hold (string $orderUniqueId)

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

Parameters

Return Value

true if the order was holded.

Example Request

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

Example Response

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

Error Codes

order.unhold (string $orderUniqueId)

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

Parameters

Return Value

true if the order was unholded.

Example Request

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

Example Response

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

Error Codes

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

0 string

string - Order unique ID

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

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

bool success

If at least one of the cancellation options was successful, the value will be true

array warnings

An array of warning messages

object order

Contains the specified (or default if no fields parameter was given) “Order Properties”.

Example Request

Attempt to cancel all items on an order:

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

Example 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

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

Add a comment to an order’s history.

This method was added in version 2021.6.

Parameters

Return Value

true if the comment was added.

Example Request

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

Example Response

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

Error Codes

Entity Properties

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

{ "note" : "Place Amazon FBA Label in a pouch" }

{ "file_name" : "amazon_fba_3425232.pdf" }

{ "file_content" : "base64-encoded file contents" }

{ "file_request" : {
  "url": "https://....",
  "auth": ["username...","password..."],
  "headers": {
    "X-Custom-Header": "header value..."
  }
} }

{ "presentation" : "once_per_order" }

{ "print_target" : "LABEL" }

{ "copies_printed" : "0" }

{ "confirmations" : [] }

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

{ "order_item_id" : 524 }

{ "order_item_ref" : "10" }

{ "sku" : "product1" }

{ "name" : "product 1" }

{ "weight" : 1.75 }

{ "weight_unit" : "lb" }

{ "row_weight" : 3.5 }

{ "row_weight_unit" : "lb" }

{ "qty_ordered" : 3 }

{ "qty_processing" : 0 }

{ "qty_shipped" : 3 }

{ "qty_canceled" : 0 }

{ "qty_backordered" : 11 }

[
  {"warehouse_id" : 1, "qty_allocated" : "2.000"},
  {"warehouse_id" : 2, "qty_allocated" : "1.000"}
]

[
  {"label" : "Serial Number - 8 Characters", "value" : "55285368"},
  {"label" : "Serial Number - 8 Characters", "value" : "55285368"}
]

[
    {"lot_number": "P7KPKDN212B", "expiration_date": "2020-11-20", "origination_date": "2019-01-23", "qty": "1.0000"}
]

Address Properties

{ "firstname" : "Davi" }

{ "lastname" : "Demir" }

{ "company" : "Demir Enterprises" }

{ "street" : "11 Times Square\nc/o Sophie Wilson" }

{ "city" : "New York" }

{ "region" : "NY" }

{ "postcode" : "10036" }

{ "country" : "US" }

{ "classification" : "com" }

{ "is_valid" : 1 }

{ "telephone" : "212.245.2100" }

{ "email" : "customer@example.com" }

Package Properties

{ "warehouse_id" : "1" }

{ "status" : "packed" }

{ "shipment_id" : "100000005" }

{ "shipment_status" : "packing" }

{ "carrier" : "ups" }

{ "manifest_courier_code" : "ups" }

{ "manifest_courier_name" : "UPS" }

{ "timestamp" : "2019-01-14T14:29:31+00:00" }

{ "shipped_at" : "2019-01-14T14:29:31+00:00" }

{ "delivered_at" : "2019-01-14T14:29:31+00:00" }

{ "weight" : "16.900" }

{ "weight_unit" : "lb" }

{ "billable_weight" : 20 }

{ "billable_weight_unit" : "lb" }

{ "dimensional_weight_divisor": "139" }

{ "dimensional_weight_divisor_unit": "in^3/lb" }

{ "dimensional_weight": "12" }

{ "dimensional_weight_unit": "lb" }

{ 
    "dimensions" : {
        "length": "16.000",
        "width": "12.000",
        "height": "8.000"
    } 
}

{ "dimension_unit" : "in" }

{ "sscc" : "008012349999999997" }

[
    { 
        "number" : "1Z49R7V80308849438", 
        "description" : "UPS Ground",
        "track_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z49R7V80308849438"
    }, { 
        "number" : "1Z49R7V29475663003", 
        "description" : "UPS Ground",
        "track_url": "https://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z49R7V29475663003"
    }
]

[
    {
        "order_item_id" : "117",
        "order_item_ref" : "10",
        "sku: "product1",
        "quantity: "2.0000"
    }, {
        "order_item_id" : "118",
        "order_item_ref" : null,
        "sku: "product2",
        "quantity: "2.0000"
    } 
]

[
    {
        "order_item_id" : "117",
        "sku: "product1",
        "quantity: "2.0000" 
    }, {
        "order_item_id" : "118",
        "sku: "product2",
        "quantity: "2.0000"
    }
] 

[
    {
        "order_item_id: "117", 
        "label" : "Serial Number - 8 Characters", 
        "value" : "55285368"
    }, {
       "order_item_id: "118", 
       "label" : "Serial Number - 8 Characters", 
       "value" : "55285369"
   }
]

Tracking Number Properties

This entity is deprecated, please use Package instead.

{ "shipment" : "100000005" }

{ "carrier" : "ups" }

{ "carrier_name" : "United Parcel Service" }

{ "description" : "Ground" }

{ "number" : "1Z9999999999999999" }

{ "date" : "2014-07-30T18:52:30+00:00" }

[
    {"sku" : "product1", "quantity" : 1 },
    {"sku" : "product2", "quantity" : 1 }
]

Status History

{ "status" : "picked" }

{ "comment" : "Shipping address classified as Commercial" }

{ "created_at" : "2014-07-24T18:51:34+00:00" }

Packing instruction Confirmation Properties

{ "confirmed_id" : "1" }

{ "confirmed_at" : "2022-02-08T14:59:38+00:00" }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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