Create a shipment

POST /api/v1/shipments creates and dispatches one physical parcel. An order shipped in three boxes is three shipments, each with its own idempotency key (for example order-1001-parcel-1 to -parcel-3) and the same customer_reference.

The rules that keep a request valid

Grams and millimetres, as integers. Convert kg to g and cm to mm and round up. Never send floats or strings for these fields.
Send both recipient_email and recipient_phone. Every delivery tier that is currently active needs both, and a parcel without them is rejected with 400.
Send zipcode as a string. Finnish postal codes have leading zeros ("00100"), and converting to a number corrupts them.
country must be "FI". No other destination is served.
Use the packed parcel: the packed weight and the outer box dimensions.

Fields

Field	Required	Typical source	Notes
`customer_reference`	no	Order number	Up to 128 characters. Printed on the label and passed to the carrier, so always set it.
`recipient_name`	yes	Shipping first and last name, or company	Up to 256 characters
`recipient_email`	in practice, yes	Customer email	A valid email address
`recipient_phone`	in practice, yes	Shipping phone	International format, e.g. `+358401234567`; up to 32 characters
`address_line1`	yes	Street and house number	Up to 256 characters
`address_line2`	no	Apartment, stairwell, c/o	Omit or `null` when empty
`city`	yes	City	Up to 128 characters
`zipcode`	yes	Postal code	String, keep leading zeros
`country`	yes	Country code	Must be `"FI"`
`sender_name`	yes	Merchant or store name	Printed as the label’s FROM
`sender_address_line1`	yes	Merchant return address
`sender_address_line2`	no
`sender_city`	yes
`sender_zipcode`	yes		String
`sender_country`	yes		Any ISO alpha-2 code. A sender outside Finland is printed as the sender name at E-Parcel’s Helsinki PO box.
`sender_email`, `sender_phone`	no	Merchant contact
`weight_g`	yes	Packed weight	Integer grams, 1 to 50,000
`length_mm`, `width_mm`, `height_mm`	yes	Packed box size	Integer millimetres, 1 to 2,000 each, in any order: the parcel is matched in any orientation
`delivery_method`	no	Checkout shipping option	See Delivery methods

Parcels are measured again at the E-Parcel hub. A parcel that does not match its declaration can be relabelled or re-dispatched as a new shipment, which you can see as scan_status on the shipment. See After dispatch.

Example request

POST /api/v1/shipments
Authorization: Bearer <api-key>
Content-Type: application/json
Idempotency-Key: order-1001-parcel-1

{
  "customer_reference": "ORDER-1001",
  "recipient_name": "Anna Aalto",
  "recipient_email": "anna@example.com",
  "recipient_phone": "+358401234567",
  "address_line1": "Mannerheimintie 1",
  "address_line2": "A 12",
  "city": "Helsinki",
  "zipcode": "00100",
  "country": "FI",
  "sender_name": "Example Store Oy",
  "sender_email": "orders@example.com",
  "sender_phone": "+358401111111",
  "sender_address_line1": "Testikatu 5",
  "sender_city": "Turku",
  "sender_zipcode": "20100",
  "sender_country": "FI",
  "weight_g": 1340,
  "length_mm": 370,
  "width_mm": 370,
  "height_mm": 270,
  "delivery_method": "HOME"
}

The response

{
  "shipment_id": 42,
  "state": "ROUTED",
  "carrier": "POSTI",
  "carrier_number": 2,
  "tracking_number": "JJFI67863998958478726",
  "label_pdf_base64": "JVBERi0xLjQK...",
  "error": null
}

state: "ROUTED" is the only success. tracking_number is the carrier’s own id, and it is also the barcode on the label. Base64-decode label_pdf_base64 to get the PDF.

Anything other than a 200 with ROUTED is covered in Errors and retries.

How a shipment is routed

E-Parcel matches the parcel against its routing rules (by weight, dimensions and the delivery methods you allow) and tries each eligible carrier in order until one accepts it. A carrier that rejects the parcel hands it to the next; one that errors is retried with backoff before moving on. The response only names the carrier that accepted it.