---
title: "POST /public/v3/orders"
method: POST
path: "/public/v3/orders"
tags: ["Manage orders"]
---

# POST /public/v3/orders

`POST /public/v3/orders`

Creates an order for Paack. One POST request creates one order.<br /><br />Optionally, use the query parameters to get a base64-encoded label in the response.

## Query parameters

- `include` 'label'
- `labelFormat` 'pdf' | 'zpl'
- `idempotent` boolean

## Request body

- AddOrderRequest
  - `external_id` string, required — Order's ID assigned by the retailer; unique within all the retailer's orders manifested to Paack. Can include special characters, excluding a comma, though for further use you need to [encode them](./special-characters). `external_id` equals `tracking_id`.
  - `customer` CreateCustomer, required — Information on the person receiving the parcels.
    - `first_name` string, required — Customer's first or full name. If the `last_name` value is not specified, the full name is split and persisted in both fields.
    - `last_name` string — Customer's last name. If not specified in the input, the last part of the first name is persisted in this field.
    - `email` string — Customer's email address.
    - `phone` string — Customer's phone number with the country prefix.
    - `has_gdpr_consent` boolean — Whether the customer gave their GDPR consent.
    - `address` unknown
    - `external_id` unknown
    - `language` unknown
  - `delivery_address` object, required — Delivery address.
    - `city` string, required — City.
    - `country` 'ES' | 'FR' | 'GB' | 'IT' | 'PT', required — Country in ISO 3166 alpha 2 format.
    - `line1` string, required — Primary address.
    - `post_code` string, required — Postcode.
    - `line2` string — Additional address information.
  - `expected_delivery_ts` object, required — Timeslot defined by the objects `start` and `end`.
    - `start` WindowDatetime, required — UTC time defined by the properties `date` and `time`.
      - `date` string, date, required — Date in `YYYY-MM-DD` format.
      - `time` string, time, required — UTC time in `hh:mm:ss` format.
    - `end` WindowDatetime, required — UTC time defined by the properties `date` and `time`.
      - `date` string, date, required — Date in `YYYY-MM-DD` format.
      - `time` string, time, required — UTC time in `hh:mm:ss` format.
  - `delivery_instructions` string — Instructions for the delivery.
  - `delivery_type` 'direct' | 'reverse' — Type of the delivery. Learn more [here](./reverse-logistcs).
  - `service_type` 'ST2' | 'ST4' | 'STZ' | 'SF2' | 'SF4' | 'SFZ' | 'NT2' | 'NT4' | 'NTH' | 'NTZ' | 'NF2' | 'NF4' | 'NFA' | 'XF4' | 'NFZ' | 'PT2' | 'PT4' | 'PTH' | 'PTA' | 'PTZ' | 'PF2' | 'PF4' | 'PFA' | 'PFZ' | 'CT2' | 'CT4' | 'CTH' | 'CTZ' | 'XFZ' | 'CF2' | 'CF4' | 'CFA' | 'CFZ' | 'WT2' | 'WT4' | 'WTH' | 'WTZ' | 'WF2' | 'WF4' | 'WFA' | 'WFZ' | 'XTZ' | 'XF2' | 'ST3' | 'DDD' | 'ND' | 'SD' | 'UNK' | 'RFA' | 'RT2' | 'RT4', required — Code that identifies the delivery day type, timeslot type, and available slot length. Learn more [here](./service-types).
  - `parcels` AddOrderRequestParcelsElem[] — Parcels included in the order. As for barcodes, generate them in the same way for both direct and reverse orders so you can use them for tracking.
    - `barcode` string, required — Barcode of the parcel.
    - `height` number, double — Height of the parcel in cm.
    - `length` number, double — Length of the parcel in cm.
    - `width` number, double — Width of the parcel in cm.
    - `weight` number, double — Actual weight of the parcel in kg.
    - `type` 'standard' — :construction: Currently input for this information is not persisted by Paack. Value equals `standard` when retrieved through the GET method.
    - `parcel_details` unknown
  - `order_details` AddCustomPropertiesString[] — Properties describing the order. :construction: Currently only the string property `sale_number`, assigning the order a custom identifier, is persisted by Paack and can be retrieved through the GET method.
    - `name` string, required — Name of the property.
    - `type` 'string' | 'array' | 'boolean' | 'null' | 'number' | 'object', required — Type of the property.
    - `value` string, required — Value of the property.
  - `pick_up_address` object, required — Pickup address. In case of reverse orders, this is the customer's address where the Paack driver should collect the parcels.
    - `city` string, required — City.
    - `country` 'ES' | 'FR' | 'GB' | 'IT' | 'PT', required — Country in ISO 3166 alpha 2 format.
    - `line1` string, required — Primary address.
    - `post_code` string, required — Postcode.
    - `line2` string — Additional address information.
  - `❗expected_pick_up_ts` object — Timeslot defined by the objects `start` and `end`.
    - `start` WindowDatetime, required — UTC time defined by the properties `date` and `time`.
      - `date` string, date, required — Date in `YYYY-MM-DD` format.
      - `time` string, time, required — UTC time in `hh:mm:ss` format.
    - `end` WindowDatetime, required — UTC time defined by the properties `date` and `time`.
      - `date` string, date, required — Date in `YYYY-MM-DD` format.
      - `time` string, time, required — UTC time in `hh:mm:ss` format.
  - `pick_up_instructions` string — Instructions for the pickup.
  - `cod_value` number, double — Amount of cash on delivery. Not persisted if the value equals 0.
  - `cod_currency` 'EUR' | 'GBP' — Currency code in ISO 4217 format.
  - `clusters` string[] — :construction: Identifiers that associate orders with each other. Learn more [here](./reverse-logistics). Note that, as of now, the array cannot be retrieved through a GET request.
  - `undeliverable_address` unknown
  - `undeliverable_instructions` unknown
  - `insured_value` unknown
  - `insured_currency` unknown

## Response `201`

Confirms the creation of an order of the `external_id` that equals the value returned in the `success.tracking_id` field. The fields `status` and `labels` are returned if the request included the query parameters.

- object — Defines the response to the POST `/orders` request.
  - `success` object — Contains the order's ID that can be used for tracking. If the request contained the query parameters, this object returns also the order's status and label.
    - `tracking_id` string, required — Order's ID assigned by the retailer; unique within all the retailer's orders manifested to Paack. Can include special characters, excluding a comma, though for further use you need to [encode them](./special-characters). `external_id` equals `tracking_id`.
    - `status` 'return_in_progress' | 'cancelled' | 'undelivered' | 'delivered' | 'reached_delivered' | 'picked_up' | 'pending' | 'draft' | 'reached_picked_up' | 'on_course' — Status of the order. `draft` if just created. Corresponds to the `order_status` field in the [webhook output](./webhook-output).
    - `labels` string — base64-encoded label.

## Other responses

- `400` — Returned in case of validation errors. The details are displayed in the `error` array. Note that the response can return only one error at once.<br /><br />To ensure a correct validation of a request:<br />- Body of the request must use a structured JSON format.<br />- All mandatory fields must be defined.<br />- Values for fields in the request must match the specific data type and format, including all limitations (e.g., `external_id` must be unique).
- `401` — Communicates a missing or expired access token for authorization. Currently used also in case of no rights to access the API.
- `403` — :construction: Communicates no rights to access the API. Contact our Customer Solutions team for help. While this HTTP error code is currently not supported the API returns 401.
- `500` — Returned in case of internal errors, which means the problem is on Paack's side.

---

[API](https://skmtc.dev/paack/apis/orders-api.md) · [All operations](https://skmtc.dev/paack/apis/orders-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/paack/orders-api/revisions/2582c46598cc/schema)