Integration lifecycle

Most production integrations follow the same sequence: authenticate, create orders, wait for optimization, then consume the packing outputs, either through a webhook or by polling.

Authenticate

Send Authorization: Api-Key YOUR_KEY on every request. Create keys in the Portal for your environment; see Authentication and Base URLs.

Create orders

Call Create an order (POST /submit-order/). Use the request body that matches your transportation mode:

• Air, OceanLCL, TruckLTL, where ALPHA palletizes SKUs: Air, LCL, and LTL

• OceanFCL, TruckFTL, where ALPHA can palletize SKUs and also accept pre-built pallets and loose boxes: FCL and FTL

Store order_id from the response and track status with [GET] List orders or [GET] Retrieve an order.

Wait for optimization

Packing optimization runs asynchronously (typically a few minutes). You can:

• Recommended: Subscribe to packing_instructions.ready and verify signatures (Webhooks). The same event id can be delivered more than once on retries, so deduplicate before side effects (Deliveries).

• Alternative: Poll [GET] Download packing instructions until the file is ready.

Retrieve outputs

• Packing instructions file: [GET] Download packing instructions (query by reference or alpha_ref). Download returns 400 while optimization is in progress.

• Structured pallets (optional): [GET] Retrieve pallet contents.

Note

reference is not unique; the API uses the newest matching order when duplicates exist. Prefer alpha_ref for an unambiguous identifier ([GET] Retrieve an order).