Parcels, addresses and carriers

These routes are the logistics part of the E-commerce API. They let your own software add the parcels you want to follow, keep your address book in step with your other tools and read the carrier catalogue. They work on the same records as the Logistics screens of your workspace: a parcel created by the API appears in your parcel list, and an address added on screen can be read here.

A key reads and writes the address book and the parcels of the account it belongs to, and nothing else. The carrier catalogue is shared and read-only.

Endpoints

The lists take limit (50 by default, 100 at most) and offset, and answer total, limit, offset and data. Authentication, the response envelope and the error format are those of Your first call.

Carriers

Read the catalogue to find the carrier of a parcel: you pass its id as carrier_id when you create the parcel.

GET /v1/carrier/list accepts these filters:

The carrier object

Parcels

Follow a parcel

POST /v1/parcel/create adds one parcel and answers 201 with the parcel.

curl -X POST https://api.ultineo.com/v1/parcel/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "1Z999AA10123456784",
    "carrier_code": "100002",
    "label": "Order 1042"
  }'

A tracking number already followed in your book is not followed twice: the answer is 409 and carries the id of the parcel that holds it.

To add several parcels in one call, send them under items, 100 at most:

{
  "items": [
    { "tracking_number": "1Z999AA10123456784", "carrier_code": "100002" },
    { "tracking_number": "LX123456789FR", "carrier_id": "carr_4f1c2a9d8e7b6a5c4d3e" }
  ]
}

The answer lists one entry per item, in order, with its tracking_number and either action (created or existing) and id, or code and reason when the item was refused. It ends with the counts created, existing, refused and total. The status is 200 when at least one parcel was created or already existed, and 422 when every item was refused. More than 100 items answers 413.

How tracking fills a parcel in

A parcel starts with the status pending. Ultineo then registers its number with the carrier in the background and writes the result on the parcel: its status in the carrier's own words (such as InTransit or Delivered), its last location, its estimated and actual delivery dates, and one event per checkpoint. Nothing is returned by the create call itself: read the parcel again, or sync the list.

The parcel object

GET /v1/parcel/detail/parc_… also returns events, the parcel's checkpoints, newest first. Each event carries id, type, description, location, lat, lng and occurred_at.

List and sync parcels

GET /v1/parcel/list accepts these filters: status, tracking_number, carrier (a carr_… identifier), recipient (an addr_… identifier), shipment (a ship_… identifier) and q, which searches the label, the number, the carrier, the destination and the recipient's names.

To follow changes without reading everything again, sync the list:

1. Call GET /v1/parcel/list?updated_since=<Unix timestamp> once.
2. Store the cursor of the answer.
3. Call GET /v1/parcel/list?cursor=<cursor> next time, and store the new cursor.

While next_cursor is not null, more rows are waiting: call again with it at once. A sync takes no offset.

Change or delete a parcel

PATCH /v1/parcel/detail/parc_… changes the fields the body names and leaves the others as they are. Two fields are specific to it:

Changing the tracking number or the carrier registers the parcel again, and its status goes back to pending. An archived parcel can no longer be changed.

DELETE /v1/parcel/detail/parc_… removes the parcel from your lists and answers { "id": "parc_…", "object": "parcel", "deleted": true }.

Addresses

Add an address

POST /v1/address/create adds an entry to your address book and answers 201.

The phone number, and the e-mail address when there is one, are checked before anything is stored, and the entry keeps their normalised form. An invalid value answers 422. If the check cannot be made, the answer is 503 and nothing is stored: send the request again later.

The same contact name at the same postal code is not stored twice: the answer is 409 and carries the id of the entry that already holds it.

The address object

List, change or delete an address

GET /v1/address/list accepts these filters: role, status, country, default=true and q.

PATCH /v1/address/detail/addr_… changes the fields the body names. It also takes status, activated or suspended. There is at most one default entry per role and only an activated entry can be it: marking one clears the others, and suspending the default entry drops its mark. An archived entry must be reactivated before it is changed.

DELETE /v1/address/detail/addr_… removes the entry from your book and answers { "id": "addr_…", "object": "address", "deleted": true }.