Create an order

POST/v1/orders

Request

{
  "externalOrderId": "PO-88213",
  "branch": "noerrebro",
  "customer": {
    "reference": "cust_8821",
    "firstName": "Alex",
    "lastName": "Doe",
    "email": "alex@example.com",
    "phone": "+45 20 12 34 56",
    "address": {
      "street": "Sortedam Dossering 55",
      "city": "Copenhagen",
      "postcode": "2100"
    }
  },
  "schedule": { "mode": "asap" },
  "weight": 2.5,
  "deliveryInstructions": "Gate code 4471, second floor"
}

Field	Type	Required	Notes
`externalOrderId`	string	No	Your order id. Unique in your organization. Always send it — see Stop duplicate orders.
`branch`	string	No	Your branch reference, or the branch UUID. Necessary if you have more than one active branch.
`zoneCode`	string	No	Send to a different connected zone.
`customer.reference`	string	No	Your customer id. Univooz uses it first to find the customer.
`customer.firstName`	string	No
`customer.lastName`	string	No
`customer.companyName`	string	No
`customer.email`	string	No	Univooz removes spaces and makes it lower case.
`customer.phone`	string	No	Univooz converts it to E.164 with your country.
`customer.address.street`	string	Yes
`customer.address.city`	string	Yes
`customer.address.postcode`	string	Yes
`customer.address.coordinates`	object	No	`{ latitude, longitude }`. Univooz uses these and does no search.
`customer.address.notes`	string	No
`schedule`	object	Yes	See Scheduling.
`weight`	number	No	Kilograms. 2 decimals, up to 99999999.99.
`numberOfPackages`	integer	No	1 to 2147483647.
`orderAmount`	number	No	The value of the goods. 2 decimals, up to 9999999999.99.
`pickupInstructions`	string	No	200 characters.
`deliveryInstructions`	string	No	200 characters.
`pickupContact`	object	No	`{ name, phone }` — the person the courier asks for.
`metadata`	object	No	Text keys and values. 50 keys, keys of 64 characters, values of 500.

A NUL character (U+0000) in a text field gives 400 invalid_request. All other characters are permitted.

Response

201 with the order object.

A rejected request writes nothing — no order, no customer, no address. A second attempt starts from clean data.

Errors

Status	Code
400	`invalid_request`
401	`invalid_api_key`
402	`subscription_inactive`
409	`duplicate_external_order_id`
413	`request_too_large`
422	`branch_required`, `branch_not_found`, `branch_not_connected`, `branch_address_missing`, `zone_not_connected`
422	`address_not_found`, `address_ambiguous`, `address_low_confidence`
422	`pickup_time_in_past`, `delivery_before_pickup`, `pickup_buffer_violation`, `no_shift_coverage`
429	`rate_limit_exceeded`

The branch decides the destination

The delivery address does not. Univooz does not check that the destination is in an area the fleet usually serves.

How Univooz finds the customer

Univooz tries three keys, in this sequence:

customer.reference
the phone number, after conversion
the email address, after conversion

The first match wins. No match makes a new customer. Univooz never uses the name.

On a match, Univooz fills empty fields only. It never replaces a value you have.

How Univooz handles the address

If you send coordinates, Univooz uses them and does no search.

If you do not, Univooz searches in your country. It accepts two levels of accuracy: the exact building, or a position calculated between two house numbers. It rejects all other results with a 422.

Univooz uses an address again if it matches an active address of that customer. The comparison removes extra spaces and ignores letter case, across street, city and postcode. Univooz never compares coordinates or notes.

Univooz avoids searches. A stored address costs nothing, and Univooz keeps each result.

The key for a kept result is the complete address. Two different house numbers in one street are two different searches.

Use Check an address when your user types the address.

Charges

Univooz records a charge at creation. Orders inside your plan cost nothing more. Test orders have no charge.