Orders
Every order belongs to one client. Orders come in by a CSV upload, the order form, the API, from a client's WooCommerce store, or from your client in their client portal. Whichever way an order arrives, it goes through the same steps, and each order shows the channel it came from.
Watch the video: From Order to Shipped Label (3 min) follows one order from the order form to a shipped label.
WooCommerce stores work today (see WooCommerce stores below). More sales channels are coming soon: Shopify stores, where orders flow in and stock levels flow back, Amazon, eBay and Etsy stores, where orders come into Lift, and TikTok Shop, where orders come in, tracking goes back to TikTok, and stock levels stay in step. For those, use a CSV upload, the order form or the API.
Your clients can also enter their own orders in their client portal, one at a time or by CSV upload, once you turn it on for them and tick the people who may submit. With Hold for my approval on, their orders wait under Orders waiting for approval until you approve them, send them back for the client to correct, or cancel them. A waiting order reserves no stock. See The Client Portal.
WooCommerce stores#
Connect a client's WooCommerce store and its orders come into Lift by themselves. There is no WordPress plugin to install.
What it does:
- Orders ready to ship come in. An order WooCommerce marks as Processing comes into Lift for that client. Cash on delivery orders that are ready to ship come in too.
- Tracking goes back. When the order ships, its tracking number is added to the WooCommerce order, and an order shipped in full is marked Completed. Lift does not email the store's shoppers directly: WooCommerce sends its usual emails, including the tracking details Lift adds to the order.
- Stock updates are opt-in for each store. They are off for every store today, so Lift does not change stock levels in WooCommerce. Turning them on for a store is coming soon.
What to know before you connect:
- The store must be a self-hosted WooCommerce store at a public HTTPS address, and WordPress itself must see the site as HTTPS (a proxy or Cloudflare in front of it must pass HTTPS through).
- One store per client.
- OpenBoxes Lift support checks each new store address before it can connect. Enter the store's address on the client's page under Clients and choose Ask for approval. Once it is approved, create the connect link there and send it to your client.
- Your client signs in to WordPress as a Shop manager who will stay (not someone about to leave) and approves OpenBoxes Lift with Read/Write access.
- If the store has a firewall, it must let OpenBoxes Lift's two addresses,
35.196.140.40and34.26.184.92, reach the store's REST API under/wp-json/(or/?rest_route=on a site without pretty permalinks). These addresses belong to OpenBoxes Lift, not to your warehouse alone. If the store uses Cloudflare Bot Fight Mode, turn it off or skip those paths for those addresses.
Some orders are held instead of coming in by themselves, for example:
- an order shipping outside the United States;
- an order with a refund on it, such as a partial refund;
- an order with a product Lift has not matched to one of the client's SKUs yet (match it under Orders, WooCommerce review).
Held orders wait on the WooCommerce review page under Orders, in Orders waiting for a decision. Open one to use the store's new version, keep Lift's, or release it for shipping once you have confirmed with the merchant. Orders paid before the store was connected are listed on the same page under Orders paid before the store was connected; they come in only when you take them, one at a time or up to 50 at once.
Order references#
Each order carries the client's own order number, its client reference. It must be unique for that client. Sending the same order again (the same reference with the same contents) creates nothing new, so a repeated upload or a retried API call is safe. The same reference with different contents is refused, so a changed order never silently replaces the first one.
A reference is up to 64 characters: letters, digits and . _ : / # -, starting with a letter or digit.
The order form#
Go to Orders and choose New order. Fill in:
- Client and Order reference (the client's own order number).
- Service level: Standard, Expedited or Next day.
- Ship by (optional) and a Delivery note (optional, up to 500 characters).
- Ship to: Name, Company, Address line 1, Address line 2, City, State or region (a code, for example CA), Postal code, Country (two letters, for example US), Phone and Email. Name, Address line 1, City and Country are required, and so is the postal code wherever the country uses one.
- Lines: a SKU and a quantity for each, up to 100 lines. Each SKU appears once per order.
Choose Save order.
Uploading orders by CSV#
Go to Orders and choose Upload CSV. The Upload orders page takes a client and a file:
- Choose a client and a file, then choose Check file.
- Check the result: Lift shows what it will create and lists any rows with a problem.
- Choose Start (it shows how many orders it will create), or Discard.
The file has one row per order line. Rows with the same client_reference are one order. Uploading the same file again creates nothing new. The file must be UTF-8, up to 2 MB and 5,000 rows, and a column Lift does not recognise rejects the file.
The columns are:
- client_reference (required): the client's order number. Rows that share it are one order.
- sku (required): one of the client's SKUs.
- quantity (required): a whole number from 1 to 1,000,000.
- service_level:
STANDARD,EXPEDITEDorNEXT_DAY. Blank meansSTANDARD. - ship_by_date:
YYYY-MM-DD. - ship_to_name, ship_to_line1, ship_to_city, ship_to_country: needed for every order. Country is two letters, for example
US. - ship_to_company, ship_to_line2, ship_to_region, ship_to_postal_code, ship_to_phone, ship_to_email: optional, except a postal code where the country uses one.
- delivery_note: up to 500 characters.
The order details (service level, ship-by date, address and note) are read from each order's first row. On its later rows, leave them blank or the same.
client_reference,sku,quantity,ship_to_name,ship_to_line1,ship_to_city,ship_to_postal_code,ship_to_country
1001,MUG-01,2,Ada Lovelace,1 Main Street,Springfield,12345,US
1001,TEA-50G,1,,,,,
1002,MUG-01,1,Alan Turing,2 High Street,Springfield,12345,US
Order statuses#
An order moves through these statuses:
- Accepted: Lift has the order.
- Ready: its stock is reserved and it is waiting to go to OpenBoxes.
- On hold: held, by you or because stock is short.
- Sending to OpenBoxes, then In OpenBoxes: Lift has created the outbound movement in OpenBoxes.
- Picking, then Picked.
- Shipped.
- Cancelled.
- Needs attention: something needs a person to look at it. The order's page says what happened and what to do next.
Holds, cancels and cut-offs#
On an order's page:
- Hold order holds it with a reason: Client asked, Address problem, Waiting for stock (Lift releases it on its own once the stock is there) or Other (take it off hold yourself). Change hold reason changes the reason.
- Take off hold releases it.
- Cancel order cancels it.
Once picking has started in OpenBoxes, a hold or a cancel has to be done in OpenBoxes instead.
Cut-offs are set under Orders, Order settings. An order accepted before its cut-off ships that business day; at or after the cut-off it ships the next one. Business days are Monday to Friday, minus your closures, in the warehouse's time zone. On the same page:
- Cut-off times: one per client and service level. No cut-off means every order ships the day it is accepted.
- Warehouse time zone: the zone cut-offs and business days use. Until your team sets it, US Eastern time is used.
- Closures: weekdays the warehouse does not ship. Weekends never ship.
The API#
Your own systems can send orders to Lift through the API, with an API key.
Keys. Create an API key in the portal under Developers, API keys (see Authentication), with the read and write scopes. The key works for the 3PL routes below only while the person who holds it is the account owner or an Admin. Send it in the X-API-Key header.
The base address is https://api.openboxes.cloud/api/v1/logistics.
Which client. Orders through this API name their client by its id: the last part of the client's page address in the portal (/clients/<id>).
The routes are:
POST /orders: create an order.POST /orders/lookup: find an order by client and reference, with the body{"clientId": "...", "clientReference": "..."}.GET /orders/{orderId}: read an order.POST /orders/{orderId}/hold: hold an order, with the body{"code": "CLIENT_REQUEST"}. The codes areCLIENT_REQUEST,ADDRESS,STOCKandOTHER.POST /orders/{orderId}/cancel: cancel an order.
Taking an order off hold, listing orders and the CSV upload are done in the portal.
Creating an order. The body has the same fields as the order form:
curl -X POST https://api.openboxes.cloud/api/v1/logistics/orders \
-H "X-API-Key: $OB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"clientId": "<client id>",
"clientReference": "1001",
"serviceLevel": "STANDARD",
"shipByDate": "2027-01-20",
"shipTo": {
"name": "Ada Lovelace",
"line1": "1 Main Street",
"city": "Springfield",
"region": "IL",
"postalCode": "12345",
"country": "US"
},
"deliveryNote": "Leave at the side door",
"lines": [
{ "sku": "MUG-01", "quantity": 2 },
{ "sku": "TEA-50G", "quantity": 1 }
]
}'
clientReference,shipTo.name,shipTo.line1,shipTo.city,shipTo.countryandlinesare required, andshipTo.postalCodewherever the country uses one. The other ship-to fields arecompany,line2,phoneandemail.serviceLevelisSTANDARD,EXPEDITEDorNEXT_DAY, and defaults toSTANDARD.linesholds 1 to 100 lines, each SKU once, each quantity from 1 to 1,000,000.
The answer is 201 with {"created": true, "order": {...}} for a new order, or 200 with "created": false when you sent the same order again. The same reference with different contents answers 409 with {"error": "order_reference_conflict"}.
Errors. A refused request answers with a JSON body naming the reason, such as {"error": "not_found"}. A body that fails validation answers 400 with {"error": "order_invalid", "problems": [{"field": "...", "code": "..."}]}, listing each field and what is wrong with it. A missing or invalid key answers 401.
