API v2 — items

Identical behavior to v1 — same required fields, same service_id resolution, idempotent on your order_id, same region handling — with the body's parcels[] spelled items[] and item_id spelled item_id. All other fields (recipient, delivery, products, gov_id, shipping_cost, …) are unchanged from Create an order.

A replayed order_id answers 200 with duplicate: true and the same body shape.

Add a new item to an order that already has more than one item. The body is a single item in the same shape as one entry of the create items[]; the item carries no Starmile tracking of its own, so the 201 returns the order's tracking_number, your order_id, and the new item by its own references. A reused item_id, or a merchant_tracking held by a real item, is 422; an unidentified package already at the hub under that barcode is matched instead. Scope: orders:update.

An order created with a single item carries that box on the order itself and has no separate items to add to — adding one is refused 409. Create a new order for the additional package instead.

Both path segments are your references — the order_id and item_idyou sent on create. Same rules as v1's parcel update: only while the order is at its flow's first step, products replaces the full list, and a late merchant_tracking that matches a package already waiting at the hub is adopted, not rejected.

POST …/items/{item_id}/cancel cancels one item (and the order, when it was the last active one); POST /api/v2/orders/{order_id}/cancel cancels the whole order. Scopes: orders:update / orders:cancel.

The v2 twin of v1's parcel split: peel one or more items out of a multi-item order and move them onto one fresh clone of the order (same service, flow, customer and destination). The body names the items with item_ids — an array of your own references (one or more, no duplicates) — and the new order with new_order_id, your own reference, so you can track and manage it like any other order. The 201follows the v2 wire: the new order's Starmile reference is tracking_number, order_id echoes your new_order_id, and each moved item carries no tracking of its own under items (item_id + merchant_tracking). Scope: orders:update.

Move a single item and the new order is a single-item order, stored the way v2 stores any single-item order — the item lives on the order itself, with no separate item to address (fetch its label and track it by its order_id, and you cannot add an item to it). Move two or more and the new order is a genuine multi-item order that keeps its items.

An ordinary order is split only while the items are at their flow's first step (else 409); a consolidation order can be split any time before its boxes are packed (an item already received or shelved can still be pulled out), and only a packed consolidation is refused 409. A folded single-item source order has no item to split off, and naming every item would leave the source empty — both 409; an item_id that names no active item is 404; a new_order_id already used, or equal to the source order_id, is 422.

Same polling model as Status updates: page with since, persist next_cursor, poll again immediately while has_more is true. Same optional filters (tracking_number, external_parent_id), same reason / reason_detail codes, and the feed still opens with the status the order was created in.

Row differences from v1: order_id is your own order reference, and item_id (set only on item-scoped rows, e.g. a single box reaching received_at_hub) replaces external_id.