Batches

POST /api/v1/shipments/batch takes up to 500 parcels and dispatches them all in one request:

{
  "shipments": [
    { "customer_reference": "ORDER-1001", "recipient_name": "Anna Aalto", "...": "..." },
    { "customer_reference": "ORDER-1002", "recipient_name": "Mikko Mäki", "...": "..." }
  ]
}

Each item is the same object you would send to POST /api/v1/shipments.

A batch never fails wholesale

The response is 200 with one result per item, in the same order, even when some items failed:

{
  "shipments": [
    { "shipment_id": 51, "state": "ROUTED", "carrier": "JYS", "carrier_number": 1,
      "tracking_number": "JYSFU29A578I64ZSIQ9", "label_pdf_base64": "JVBERi0x...", "error": null },
    { "shipment_id": 52, "state": "UNROUTABLE", "carrier": null, "carrier_number": null,
      "tracking_number": null, "label_pdf_base64": null, "error": "all carriers rejected the shipment" }
  ]
}

Check every item. A failed item has state UNROUTABLE or FAILED, an error string and a real shipment_id.

Only a problem with the shape of the request rejects the whole batch with 422, for example any item with a country other than FI.

Retrying failed items

Caution

Batches don’t support idempotency keys. A batch request carrying an Idempotency-Key header is rejected with 400 and nothing is created.

Retrying a failed batch item through the batch endpoint creates a new shipment. Retry failed items one at a time through the single endpoint, with an idempotency key, when safe retries matter.

Batch size and timeouts

A batch has no server-side deadline: every parcel is dispatched before the response returns. Start with batches of about 50, measure how long they take, and keep each batch well inside your client timeout.