Skip to main content
POST
Requires the consignments:write scope. Customer-scoped API keys can add parcels to their own consignments. Use this when a shipment turns out to have more boxes than were declared at create. Parcels can be added while the consignment is still editable. The request is refused with 409 consignment_locked once the consignment:
  • was deleted (cancelled),
  • is on hold,
  • has a final-mile (last-mile) carrier label booked,
  • has been processed in the warehouse (scanned into a group),
  • is on a manifest,
  • has been handed to a partner, or
  • has a delivered parcel.
The error message says which of these applies. In that case, create a new consignment for the extra parcel.
The same editable rule applies to customer-scoped API keys (and the customer portal) when they change the receiver (PATCH /consignments/{id} receiver fields) or generate a new own-template label (POST /labels/generate). Downloading (reprinting) an existing label is always allowed.
First-, middle-mile and pre-applied labels on the other parcels don’t block the add and are left as they are. The new parcel starts without a carrier label. To book one, call POST /consignments/{id}/labels; it only labels parcels that don’t have a label yet. To render your own label template for the new parcel, pass labels. When the workspace has a parcel barcode structure configured (Settings → Defaults), the new parcel gets a generated_barcode from it, just as at create. The consignment’s tracking number does not change. A parcel.added timeline event is recorded and delivered to your webhooks.
​
integer
required
The consignment ID.

​
Body

The body is one parcel in the same shape as parcels[] on create.
​
number
required
Parcel weight, in the consignment’s weight_unit. Must be greater than 0.
​
string
default:"BOX"
BAG, BOX, ENVELOPE, PALLET, or TUBE.
​
number
Height, in the consignment’s measurement_unit.
​
number
Width, in the consignment’s measurement_unit.
​
number
Depth (length), in the consignment’s measurement_unit.
​
string
Your reference for the parcel (max 100 chars).
​
string
Your own parcel barcode. It must not already belong to another parcel in the workspace (409 barcode_exists).
​
number
Declared parcel value. Requires currency_code.
​
string
ISO 4217 currency of declared_value.
​
array
The parcel’s contents, with the same fields as parcels[].items[] on create. order_ref must name an order that is already on the consignment.
​
string
default:"none"
Your own label template for the new parcel. sync renders it before the response, and the label URL is returned in label. async renders it in the background and signals completion with the label.generated webhook. none means no label is rendered; you can generate one later with POST /labels/generate.
Pre-applied carrier labels (carriers[]) and nested orders[] can only be sent when the consignment is created.

​
Response

Returns 201.
​
object
The new parcel, including generated_barcode, its identifiers, and its items.
​
integer
The number of parcels on the consignment after the add.
​
object
Only returned with labels: "sync". Contains label_url and barcode_value.
​
array
Only returned when labels: "sync" failed, for example because no template is set up. The parcel is still added.