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.

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 The order is being packed. It can no longer be modified.
Partial The order was partially fulfilled. The remaining line items will be fulfilled when more inventory arrives.
Fulfilled The order was completely 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
DELETE /orders/{id} Deletes an order

Properties

created

{"created": "2016-02-23 15:43:03"}

String - The shop order date and time in UTC if available. Otherwise, the date and time the order was created in BoxC. This property is immutable.
consignor

{
    "consignor": {
        "name": "Generic Company, LLC",
        "phone": "555-123-4567",
        "street1": "1 WORLD WAY",
        "street2": "",
        "city": "SHENZHEN",
        "province": "GUANGDONG",
        "postal_code": "518000",
        "country": "CN"
    }
}

Name, address and phone number for the consignor (sender) which is used for Customs. This property will inherit the user's phone number and company address if it's not provided. Not required.

name: String(40) - The consignor's name. Required.
phone: String(20) - The consignor's phone number. Required.
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. Required.
postal_code: String(10) - The consignor's postal code. Required.
country: String(2) - The consignor's country in ISO 3166-1 alpha-2 format. Required.
from

{
    "from": {
        "name": "My Company Name",
        "street1": "113 INTL BROADWAY",
        "street2": "",
        "city": "LOS ANGELES",
        "province": "CA",
        "postal_code": "91013",
        "country": "US"
    }
}

Information about the sender. This will appear as the return address. If any conditional property is missing then it will inherit your default return address. The default return address can be set using the Users resource. If the user's default return address is not set then it will use a return address belonging to BoxC.

name: String(40) - Can be a sender's name or company name. Required.
street1: String(40) - The sender's street address. Conditional.
street2: String(40) - Additional space for the sender's street address. Not required.
city: String(40) - The sender's city. Conditional.
province: String(40) - The sender's province or state. Conditional.
postal_code: String(10) - The sender's postal code or ZIP Code. Conditional.
country: String(2) - The senders's country in ISO 3166-1 alpha-2 format. Conditional.

fulfillments

{
    "fulfillments": [
        {
            "created": "2016-02-24 01:59:32",
            "fulfillment_fee": 0.99,
            "id": 10931,
            "service": "BoxC",
            "shipping_cost": 3.38,
            "tracking_number": "9261499976491500023573",
            "tracking_url": "https:\/\/www.boxc.com\/h\/track?id=9261499976491500023573"
        }
    ]
}

Array - An array of fulfillment objects for this order. Set by the system.

created: The date and time this fulfillment was made.
fulfillment_fee: The fee for fulfilling this item or order.
id: The unique ID for this fulfillment.
service: The shipping provider and/or service for this fulfillment.
shipping_cost: The cost of shipping this fulfillment.
tracking_number: The tracking number for this fulfillment. Default: null
tracking_url: The tracking URL for this fulfillment if available.
id

{"id": 1029210}

Integer - The order ID. Set by the system.
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"
        }
    ]
}

An array of line items belonging to this order. Only present when retrieving a single order.

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 product 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.
override

{"override": false}

Boolean - Whether or not to override the address verification for this order. Not required. Default is false.
packing_slip

{"packing_slip": true}

Boolean - Whether or not this order requires a packing slip for each fulfillment for an additional fee. Not required. Default is false.
partial_fulfillment

{"partial_fulfillment": false}

Boolean - Whether or not this order should be fulfilled partially. If true, the warehouse will fulfill line items as their products arrive in the event there is insufficient quantity.
products

{"products": 2}

Integer - The number of unique products in this order. Set by the system.
quantity

{"quantity": 3}

Integer - The total number of items in this order. Set by the system.
service

{"service": "BoxC"}

String - The type of shipping service you want to use for this shipment. Not required. Available services are:
  • BoxC (default)
  • BoxC Plus
  • BoxC Priority
shop

{
    "shop": {
        "id": "my-shop",
        "name": "My Store",
        "order_id": "30338272",
        "type": "Shopify"
    }
}

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.
type: (String) The shop type. Set by the system.
status

{"status": "Processing"}

String - The order's current status. Not required. Users have two options:

  • Holding
  • Processing
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.
GET
/orders/{id}
Retrieves an order
request
GET /orders/11102
response

HTTP/1.1 200 OK

{
    "order": {
        "consignor": {
            "name": "Generic Company, LLC",
            "phone": "555-123-4567",
            "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",
                "fulfillment_fee": 0.99,
                "id": 4923,
                "service": "BoxC",
                "shipping_cost": 3.38,
                "tracking_number": "9261499976491500023573",
                "tracking_url": "https:\/\/www.boxc.com\/h\/track?id=9261499976491500023573"
            }
        ],
        "id": 11102,
        "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"
            }
        ],
        "override": false,
        "packing_slip": true,
        "partial_fulfillment": false,
        "products": 1,
        "quantity": 1,
        "service": "BoxC",
        "shop": {
            "id": "my-shop",
            "name": "My Shop",
            "order_id": null,
            "type": "BoxC"
        },
        "status": "Fulfilled",
        "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"
        }
    }
}
POST
/orders
Creates an order
request
POST /orders
{
    "order": {
        "created": "2016-02-21 11:50:30",
        "from": {
            "name": "My Company, LLC"
        },
        "line_items": [
            {
                "quantity": 1,
                "sku": "MYSKU1022"
            },
            {
                "quantity": 1,
                "sku": "OtherSKU#12"
            }
        ],
        "override": true,
        "packing_slip": true,
        "partial_fulfillment": false,
        "service": "BoxC",
        "shop": {
            "id": "my-shop",
            "order_id": "CustomOrder#"
        },
        "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"
        }
    }
}
response

HTTP/1.1 200 OK

{
    "order": {
        "consignor": {
            "name": "Generic Company, LLC",
            "phone": "555-123-4567",
            "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": [],
        "id": 112019,
        "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"
            },
            {
                "dg_code": null,
                "fulfilled": false,
                "fulfillment_id": null,
                "hs_code": null,
                "name": "S White T-Shirt",
                "product_id": 1230,
                "quantity": 1,
                "sku": "OtherSKU#12"
            }
        ],
        "override": true,
        "packing_slip": true,
        "partial_fulfillment": false,
        "products": 2,
        "quantity": 2,
        "service": "BoxC",
        "shop": {
            "id": "my-shop",
            "name": "My Shop",
            "order_id": "CustomOrder#",
            "type": "BoxC"
        },
        "status": "Processing",
        "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"
        }
    }
}
PUT
/orders/{id}
Updates an order
request
PUT /orders/9281
{
    "order": {
        "from": {
            "name": "My Company, LLC"
        },
        "line_items": [
            {
                "quantity": 1,
                "sku": "MYSKU1022"
            }
        ],
        "override": false,
        "packing_slip": true,
        "partial_fulfillment": true,
        "service": "BoxC",
        "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"
        }
    }
}
response

HTTP/1.1 200 OK

{
    "order": {
        "consignor": {
            "name": "Generic Company, LLC",
            "phone": "555-123-4567",
            "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": [],
        "id": 9281,
        "line_items": [
            {
                "dg_code": null,
                "fulfilled": false,
                "fulfillment_id": null,
                "hs_code": null,
                "name": "XL T-Shirt",
                "product_id": 1022,
                "quantity": 1,
                "sku": "MYSKU1022"
            }
        ],
        "override": false,
        "packing_slip": true,
        "partial_fulfillment": true,
        "products": 1,
        "quantity": 1,
        "service": "BoxC",
        "shop": {
            "id": "my-shop",
            "name": "My Shop",
            "order_id": "CustomOrder#",
            "type": "BoxC"
        },
        "status": "Processing",
        "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"
        }
    }
}
DELETE
/orders/{id}
Deletes an order
request
DELETE /orders/20194
response

HTTP/1.1 200 OK