Orders
The Orders resource allows you to create, read, update, and delete orders that are meant to be fulfilled by BoxC. If you wish to manually create an order for a third party shop you must provide the shop.id
and shop.order_id
. Neither property can be updated. The system will push tracking information to the shop when the order is fulfilled if both properties are set. Clients can force which warehouse is used for order fulfillment by setting the warehouse.id
property.
Order Status
The following table lists all possible states of an order indicated by its status
property. Updating an order that is 'Ready' will reset its status to 'Processing' and restore product quantities until it's processed by the system again.
Status | Description |
---|---|
Backordered | There is insufficient quantity for one or more line items. The system will change the status once more inventory is added. |
Exception | There is a problem with the order such as missing or invalid information. The user must correct the problem before the order can be processed by the system. |
Holding | The order is being delayed from processing by the user. |
Processing | The order is waiting for the system to process it. Default state. |
Ready | The order is assigned to a warehouse for packing and quantities were deducted. |
Packing | One or more line items are being packed. It can't be edited in this state. |
Partial | The order was partially fulfilled. The remaining line items will be fulfilled when more inventory arrives. |
Fulfilled | The order was completely fulfilled. |
Archived | The system archives orders that were fulfilled at least 90 days in the past. |
Pruning Orders
The system routinely prunes or closes out orders in the system more than 365 days ago. The start time is based on the placed_at
and not the created
datetime. What happens to the order depends on its current state at the time of pruning.
- Unfulfilled (not Packing, Partial, Fulfilled) orders are deleted.
- Partially fulfilled orders (Holding, Packing, Partial) are bumped to Fulfilled.
- Orders in Packing have their unfulfilled line items and fulfillment objects deleted, and are bumped to Fulfilled.
Actions
GET /orders |
Retrieves a paginated list of orders |
GET /orders/{id} |
Retrieves an order |
POST /orders |
Creates an order |
PUT /orders/{id} |
Updates an order |
POST /orders/status |
Change the status of one or more orders |
DELETE /orders/{id} |
Deletes an order |
Properties
created |
|
consignee |
{ "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" } } Object (Optional). Details about the consignee / buyer. The system will use the shipping address as the consignee address if one isn't provided. Some countries require a tax / passport ID from the buyer. name: String(40) - The consignee's name. Required.phone: String(20) - The consignee's phone number. Conditional. email: String(64) - The consignee's email address. Conditional. id: String(20) - The consignee's Tax ID, GSTIN, Passport, ABN, Vendor ID, etc. Conditional. street1: String(40) - The consignee's street address. Required. street2: String(40) - Additional space for the consignee's street address such as apartment, condo, or unit number. Optional. city: String(40) - The consignee's city. Required. province: String(40) - The consignee's province or state code. Conditional. postal_code: String(10) - The consignee's postal code. Conditional. country: String(2) - The consignee's country in ISO 3166-1 alpha-2 format. Required. |
consignor |
{ "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "email": "consignor@test.com", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" } } Address and other details for the consignor (sender) which is required for customs clearance. Required. name: String(40) - The consignor's name. Required.phone: String(20) - The consignor's phone number. Required. email: String(64) - The consignor's email address. Conditional for some countries. Default: null id: String(20) - The consignor's Tax ID, GSTIN, ABN, Vendor ID, etc. Optional. street1: String(40) - The consignor's street address. Required. street2: String(40) - Additional space for the consignor's street address such as apartment, condo, or unit number. Not required. city: String(40) - The consignor's city. Required. province: String(40) - The consignor's province or state code. Conditional. postal_code: String(10) - The consignor's postal code. Conditional. country: String(2) - The consignor's country in ISO 3166-1 alpha-2 format. Required. |
exception_on_failure |
{"exception_on_failure": true}Boolean - If true then the order will be created and placed in the "Exception" state when there are address or routing errors. Only used when creating orders. Not required. Default: false. |
from |
{ "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" } } This will appear as the return address on labels. Optional. A default return address will be used if one isn't provided in the request.
name: String(40) - Can be a sender's name or company name. Required. |
fulfillments |
{ "fulfillments": [ { "created": "2016-02-24 03:11:32", "fulfilled": "2016-02-24 17:17:17", "fulfillment_fee": 1, "id": 4923, "packed": "2016-02-24 15:15:15", "packaging_fee": 0.1, "packing_slip_fee": 0.25, "service": "BoxC Parcel", "shipment_id": 123456, "shipping_cost": 0, "tracking_number": "9261499976491500023573", "tracking_url": "https:\/\/track.boxc.com\/?id=9261499976491500023573" } ] } Array - An array of fulfillment objects for this order. Not all properties are present when searching. Set by the system. created: The datetime this fulfillment was initiated.fulfilled: The datetime this fulfillment was finalized. fulfillment_fee: The fee for fulfilling this item or order. id: The unique ID for this fulfillment. packed: The datetime this fulfillment was packed. packaging_fee: The fee for packaging the fulfillment. packing_slip_fee: The fee for printing and including a packing slip. service: The shipping provider and/or service for this fulfillment. shipment_id: The shipment ID if fulfilled by BoxC. shipping_cost: The cost of shipping this fulfillment using a third party. tracking_number: The tracking number for this fulfillment. Default: null tracking_url: The tracking URL for this fulfillment if available. |
gift_message |
|
id |
|
ignore_bad_address |
|
insurance |
|
line_items |
{ "line_items": [ { "dg_code": null, "fulfilled": false, "fulfillment_id": null, "hs_code": null, "name": "XL T-Shirt", "product_id": 1029, "quantity": 1, "sku": "92820183446", "sold_for": 4.99 } ] } An array of line items belonging to this order. Not all properties are present when searching. dg_code: The Dangerous Goods code for the product if applicable. Set by the system.fulfilled: Whether or not this line item was fulfilled. Set by the system. fulfillment_id: The fulfillment ID created to fulfill this line item. Set by the system. hs_code: The HS code for the line item if applicable. Set by the system. name: The product name. Set by the system product_id: The product ID. Set by the system. quantity: The product quantity that needs to be fulfilled. sku: The product SKU belonging to the order's shop. sold_for: Allows the user to override the product's value in case the line item was sold for a different price. This property represents the total value for the line item. Default is null. |
packing_slip |
|
partial_fulfillment |
|
placed_at |
|
products |
|
quantity |
|
service |
|
shop |
{ "shop": { "id": "my-shop", "name": "My Store", "order_id": "30338272", "type": "BoxC" } } Information about the shop this order is linked to. Required. This object is immutable. id: (String) The shop ID. Required.name: (String) The shop name. Set by the system. order_id: (String) The shop order ID if available. Max length: 32. Not required. You must provide this for the system to push tracking information to the third party shop. Must be unique for the shop. type: (String) The shop type. Set by the system. |
signature_confirmation |
|
status |
String - The order's current status. Not required. Users have two options:
|
terms |
|
to |
{ "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" } } Information about the recipient and their shipping address. company_name: String(40) - The company name. Not required.name: String(40) - The recipient's name. Required. phone: String(20) - The recipient's phone number. Conditional. email: String(64) - The recipient's email address. Conditional. street1: String(40) - The recipient's street address. Required. street2: String(40) - Additional space for the recipient's street address. Not required. city: String(40) - The recipient's city. Required. province: String(40) - The recipient's province or state. Conditional. postal_code: String(10) - The recipient's postal code or ZIP Code. Conditional. country: String(2) - The recipient's country in ISO 3166-1 alpha-2 format. Required. |
warehouse |
{ "warehouse": { "id": "WH0SZ001" } } Object - Declare the warehouse where you want this order fulfilled. It will not be fulfilled until sufficient quantity exists at the specified warehouse. View the Warehouses resource for a list. Optional. id: String|null - The unique warehouse ID. Required. Default is null which is default system behavior. |
created_min |
The inclusive date to begin the search in YYYY-MM-DD format. Default is null. |
created_max |
The inclusive date to end the search in YYYY-MM-DD format. Default is null. |
limit |
The number of results to return. Max: 100. Default: 50. |
order |
Sort the results by the created property. Options are "asc" for ascending, or "desc" (default) for descending order. |
page_token |
Used for selecting the page after the initial query. |
product.id |
Filter to return only orders containing the matching product. |
shipping_address.name |
Filter to return only orders matching the shipping addressee's name. |
shop.id |
Filter to return only orders belonging to a particular shop you own. |
shop.order_id |
Filter to return only orders with a matching shop order ID. |
status |
Filter to return only orders with a particular status. Returns all by default. |
GET /orders
limit=50&order=desc&status=Processing&shop.id= \ &shop.order_id=&shipping_address.name=&product.id=
HTTP/1.1 200 OK
{ "orders": [ { "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "email": "consignor@test.com", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2016-02-23 14:42:59", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "fulfillments": { "created": "2018-07-31 05:26:07", "fulfilled": "2018-07-31 16:17:18", "fulfillment_fee": 1.5, "id": 419666, "packed": "2018-07-31 15:15:15", "service": "BoxC Priority", "shipment_id": 1240891, "shipping_cost": 5.04, "tracking_url": "https:\/\/track.boxc.com\/?id=9200190181596700475512", "tracking_number": "9200190181596700475512" }, "gift_message": "Have a wonderful day!", "id": 20189, "ignore_bad_address": false, "insurance": true, "line_items": [ { "sku": "1001-AB-LG", "quantity": 1, "product_id": 119780, "fulfillment_id": 419666, "fulfilled": true, "sold_for": 24.95 }, { "sku": "1001-SB-LG", "quantity": 1, "product_id": 120081, "fulfillment_id": 419666, "fulfilled": true, "sold_for": 24.95 } ], "packing_slip": true, "partial_fulfillment": false, "products": 1, "quantity": 1, "service": "BoxC Parcel", "shop": { "id": "my-shop", "name": "My Shop", "order_id": null, "type": "BoxC" }, "status": "Fulfilled", "terms": "DDU", "to": { "company_name": null, "name": "John Doe", "email": null, "phone": "555-123-4562", "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" }, "warehouse": { "id": null } }, { "id": 20190, "...": "..." } ], "next_page": "ZGF0ZV9lbmQ9MjAyMy0wNy0yOCZsaW1pdD01MCZvcmRlcj1kZXNjJnBhZ2U9MSZzdGF0dXM9Jmxhc3RfaWQ9NDUyODc2Nw==" }
GET /orders/11102
HTTP/1.1 200 OK
{ "order": { "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "email": "consignor@test.com", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2016-02-23 14:42:59", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "fulfillments": [ { "created": "2016-02-24 03:11:32", "fulfilled": "2016-02-24 16:17:18", "fulfillment_fee": 1, "id": 4923, "packed": "2016-02-24 15:15:15", "packaging_fee": 0.1, "packing_slip_fee": 0.25, "service": "BoxC Parcel", "shipment_id": 123456, "shipping_cost": 0, "tracking_number": "9261499976491500023573", "tracking_url": "https:\/\/track.boxc.com\/?id=9261499976491500023573" } ], "gift_message": "Have a wonderful day!", "id": 11102, "ignore_bad_address": false, "insurance": true, "line_items": [ { "dg_code": null, "fulfilled": true, "fulfillment_id": 4923, "hs_code": null, "name": "S White T-Shirt", "product_id": 1022, "quantity": 1, "sku": "MYSKU1022", "sold_for": 4.99 } ], "packing_slip": true, "partial_fulfillment": false, "placed_at": "2016-02-23 14:42:59", "products": 1, "quantity": 1, "service": "BoxC Parcel", "shop": { "id": "my-shop", "name": "My Shop", "order_id": null, "type": "BoxC" }, "status": "Fulfilled", "terms": "DDU", "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" }, "warehouse": { "id": null } } }
POST /orders
{ "order": { "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "created": "2016-02-21 11:50:30", "from": { "name": "My Company, LLC" }, "gift_message": "Have a wonderful day!", "ignore_bad_address": false, "insurance": true, "line_items": [ { "quantity": 1, "sku": "MYSKU1022", "sold_for": 4.99 }, { "quantity": 1, "sku": "OtherSKU#12", "sold_for": null } ], "packing_slip": true, "partial_fulfillment": false, "service": "BoxC Parcel", "shop": { "id": "my-shop", "order_id": "CustomOrder#" }, "terms": "DDU", "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" }, "warehouse": { "id": "WH0SZ001" } } }
HTTP/1.1 200 OK
{ "order": { "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "email": "consignor@test.com", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2016-02-21 11:50:30", "from": { "name": "My Company, LLC", "street1": "311 SAINT NICHOLAS AVE, 2D", "street2": "", "city": "RIDGEWOOD", "province": "NY", "postal_code": "11385", "country": "US" }, "fulfillments": [], "gift_message": "Have a wonderful day!", "id": 112019, "ignore_bad_address": false, "insurance": true, "line_items": [ { "dg_code": null, "fulfilled": false, "fulfillment_id": null, "hs_code": null, "name": "M Pink T-Shirt", "product_id": 1022, "quantity": 1, "sku": "MYSKU1022", "sold_for": 4.99 }, { "dg_code": null, "fulfilled": false, "fulfillment_id": null, "hs_code": null, "name": "S White T-Shirt", "product_id": 1230, "quantity": 1, "sku": "OtherSKU#12", "sold_for": null } ], "packing_slip": true, "partial_fulfillment": false, "placed_at": "2016-02-23 14:42:59", "products": 2, "quantity": 2, "service": "BoxC Parcel", "shop": { "id": "my-shop", "name": "My Shop", "order_id": "CustomOrder#", "type": "BoxC" }, "status": "Processing", "terms": "DDU", "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" }, "warehouse": { "id": "WH0SZ001" } } }
PUT /orders/9281
{ "order": { "from": { "name": "My Company, LLC" }, "gift_message": "Have a wonderful day!", "ignore_bad_address": false, "insurance": true, "line_items": [ { "quantity": 1, "sku": "MYSKU1022", "sold_for": 4.99 } ], "packing_slip": true, "partial_fulfillment": true, "service": "BoxC Parcel", "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" } } }
HTTP/1.1 200 OK
{ "order": { "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "email": "consignor@test.com", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2016-02-21 11:50:30", "from": { "name": "My Company, LLC", "street1": "311 SAINT NICHOLAS AVE, 2D", "street2": "", "city": "RIDGEWOOD", "province": "NY", "postal_code": "11385", "country": "US" }, "fulfillments": [], "gift_message": "Have a wonderful day!", "id": 9281, "ignore_bad_address": false, "insurance": true, "line_items": [ { "dg_code": null, "fulfilled": false, "fulfillment_id": null, "hs_code": null, "name": "XL T-Shirt", "product_id": 1022, "quantity": 1, "sku": "MYSKU1022", "sold_for": null } ], "packing_slip": true, "partial_fulfillment": true, "placed_at": "2016-02-21 11:50:30", "products": 1, "quantity": 1, "service": "BoxC Parcel", "shop": { "id": "my-shop", "name": "My Shop", "order_id": "CustomOrder#", "type": "BoxC" }, "status": "Processing", "terms": "DDU", "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" }, "warehouse": { "id": "WH0SZ001" } } }
POST /orders/status
{ "orders": [ { "id": 10004, "status": "Holding" }, { "id": 10005, "status": "Processing" } ] }
HTTP/1.1 200 OK
{ "orders": [ { "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "email": "consignor@test.com", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2016-02-23 14:42:59", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "gift_message": "Have a wonderful day!", "fulfillments": [], "id": 10004, "ignore_bad_address": false, "insurance": true, "line_items": [ { "dg_code": null, "fulfilled": true, "fulfillment_id": 4923, "hs_code": null, "name": "S White T-Shirt", "product_id": 1022, "quantity": 1, "sku": "MYSKU1022", "sold_for": 4.99 } ], "packing_slip": true, "partial_fulfillment": false, "placed_at": "2016-02-24 03:11:32", "products": 1, "quantity": 1, "service": "BoxC Parcel", "shop": { "id": "my-shop", "name": "My Shop", "order_id": null, "type": "BoxC" }, "status": "Holding", "terms": "DDU", "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" }, "warehouse": { "id": null } }, { "consignee": { "name": "Addressee John", "phone": "555-456-7890", "email": null, "id": null, "street1": "2959 ANCHOR DR", "street2": null, "city": "MESQUITE", "province": "TX", "postal_code": "75150", "country": "US" }, "consignor": { "name": "Generic Company, LLC", "phone": "555-123-4567", "email": "consignor@test.com", "id": null, "street1": "1 WORLD WAY", "street2": "", "city": "SHENZHEN", "province": "GUANGDONG", "postal_code": "518000", "country": "CN" }, "created": "2016-02-23 14:42:59", "from": { "name": "My Company Name", "street1": "113 INTL BROADWAY", "street2": "", "city": "LOS ANGELES", "province": "CA", "postal_code": "91013", "country": "US" }, "fulfillments": [ { "created": "2016-02-24 03:11:32", "fulfilled": "2016-02-24 09:11:50", "fulfillment_fee": 1, "id": 4923, "packaging_fee": 0.1, "packed": "2016-02-24 08:10:50", "packing_slip_fee": 0.25, "service": "BoxC Parcel", "shipment_id": 123456, "shipping_cost": 0, "tracking_number": "9261499976491500023573", "tracking_url": "https:\/\/track.boxc.com\/?id=9261499976491500023573" } ], "id": 10005, "ignore_bad_address": false, "insurance": true, "line_items": [ { "dg_code": null, "fulfilled": true, "fulfillment_id": 4923, "hs_code": null, "name": "S White T-Shirt", "product_id": 1022, "quantity": 1, "sku": "MYSKU1022", "sold_for": 4.99 } ], "packing_slip": true, "partial_fulfillment": false, "placed_at": "2016-02-24 03:11:32", "products": 1, "quantity": 1, "service": "BoxC Parcel", "shop": { "id": "my-shop", "name": "My Shop", "order_id": null, "type": "BoxC" }, "status": "Fulfilled", "terms": "DDU", "to": { "company_name": null, "name": "John Doe", "phone": "555-123-4562", "email": null, "street1": "1500 Marilla St", "street2": null, "city": "Dallas", "province": "TX", "postal_code": "75201", "country": "US" }, "warehouse": { "id": null } } ] }
DELETE /orders/20194
HTTP/1.1 200 OK