Shipping is one server action that works everything out: where the order ships from, the boxes, the carrier service, and a label for every box. It first answers ready or needs. When something is missing, it says exactly what is missing, and the fixes are saved where they belong, so the next order with the same product just ships.
Video tutorials for this topic
Ask first
- Which order? Its order number.
- Anything going by freight or later? Only if the check says an item is too heavy for a parcel carrier.
- Nothing else up front. The check says what it needs.
Steps
1. Orders: check the order
Real action: POST shipping/order/ship with { orderNumber, check: true }. This buys nothing. The answer is one of:
ready, with where it ships from;needs, withmissing[];shipped: everything on the order has already shipped;nothing: there are no physical items (e.g. only downloads or services).
On screen: open the order on its Shipping tab (/order?openId=<order sk>&tab=shipping). When the order is ready, it shows the green Ship in one click button with "Ships from …". Otherwise it shows an amber list with Fix what's missing.
Hands on: the missing[] codes.
2. Fix what's missing
Each code has its fix. For a check, send fixes with check: true: the fixes are saved and nothing is bought.
| Code | What it means | The fix |
|---|---|---|
product_sizes | a product has no weight or box size | ask the person for each product's packed weight and size. Send fixes.productSizes keyed by the item's SKU (else product id, else name): { weight, weightUnit, length, width, height, dimensionUnit }. Saved on the product. |
packing | many units would go in many small boxes | ask how many fit in one box and the box size. Send fixes.packing[<key>] with { quantity, length, width, height, dimensionUnit, weight? }. Saved on the product as its packaging. |
to_address | the delivery address is missing or incomplete | ask for it, or the customer. Send fixes.toAddress with { name, street1, city, state, zip, country }. Saved on the order. |
ship_from | more than one location could ship it | ask which one. Send fixes.fromLocationId (and rememberLocation: true if it is always that one). |
from_phone | carriers need a sender phone | ask for it. Send fixes.fromPhone. Saved on the location. |
no_location / from_address | there is no ship-from address, or it is incomplete | complete the location in Business locations (/business-locations?openId=<sk>). |
no_integration / agreement | shipping is not set up, or the shipping service agreement is not accepted | a person sets up the carrier in Shipping → settings, or accepts the agreement. The AI does neither. |
Never invent a weight or size to get past the check. A wrong weight buys a wrong label.
Check: run the check again until it answers ready. Then say where it ships from.
3. Shipping: buy the labels
Stop: buying labels costs money and emails the customer the tracking. Today that is one email per label. Show:
- the order;
- where it ships from and to;
- how many boxes, if known.
Wait for yes.
On screen: Ship in one click on the order's Shipping tab.
Real action: POST shipping/order/ship with { orderNumber } (no check).
The server packs the boxes and picks the carrier service: the exact service the customer chose at checkout when every box can use it, otherwise the cheapest. It then buys every box's label.
If an item turns out too heavy for a parcel carrier (oversize), the call comes back before buying anything. Ask the person whether to correct its weight, send it by freight (carrier plus tracking, sent as fixes.freight) or ship it later (fixes.later), then send the call again.
Hands on: the result: labels[], chosen (carrier, service and why), totalCost, plus any freight[] and later[] items, and complete.
Check:
- The order's status is
shipped, orpartially-shippedwhen items were left for later. - Its Shipping tab lists each label with tracking.
- Each shipment opens in Shipping (
/shipping?openId=<shipment sk>).
4. Print
In the one-click result, Print prints one label and Print all prints every label on one page. A label can also be reprinted later from the shipment. Printing straight to a thermal printer is not available yet: labels print through the browser.
When it's done
Tell the person:
- the order number;
- the carrier and service, and why that one;
- how many labels, with their tracking numbers;
- the total postage;
- anything left for later or sent by freight.
Then say that the order is marked shipped and the customer has been emailed the tracking. Open the order on its Shipping tab.
International orders needing customs forms and batch shipping of many orders at once are not available yet. Say so rather than trying another way.