API overview

The E-commerce API lets your own tools fill your shop and read it back: a migration script, an ERP sync or a supplier feed sends records in batches, and reads any single record to check what was saved. Its logistics routes let your own software add the parcels you want to follow, keep your address book in step and read the carrier catalogue. It is a JSON-over-HTTPS API. This page gives the rules every call shares, then lists the reference articles.

Base address

Every request goes to:

https://api.ultineo.com/v1/

Only HTTPS is served. One endpoint needs no key, and you can use it to check that the host is reachable:

curl https://api.ultineo.com/health

{
  "code": 200,
  "title": "OK",
  "response": "api gateway"
}

Authentication

Send your shop's API key as a Bearer token in the Authorization header of every call. A key starts with sk-project-, belongs to one shop and holds scopes: each resource has one read scope and one write scope, and a call that is short of its scope is refused with 403. You create a key in your workspace, on the API Access tab of your project; the API keys article of this help center gives the steps. The header and the table of scopes are in Your first API call.

The response envelope

Every endpoint answers with the same three keys, on success and on failure alike. Read the HTTP status code first, then read response.

Errors

A failed call uses the same envelope as a successful one: read the HTTP status code, then read response for a message describing what went wrong. Error codes lists every status the API returns, its messages and what to do about each.

Limits

• Requests — Too many requests in a short time are answered with 429. Wait for the number of seconds given in the Retry-After header, then retry.
• Body — A request body is no larger than 200,000 bytes. A larger one is answered with 413: send smaller batches.
• Batch — Each resource has its own batch limit, from 25 to 500 items, given in its endpoint table. A batch over the limit is answered with 422: split it.
• Lists — The imported resources are read back one record at a time, with no list, no search and no pagination. The lists of Parcels, addresses and carriers take limit (50 by default, 100 at most) and offset.

Versioning

The version of the API is in the path: the routes of this reference are under /v1/.

Test with dry_run

With "dry_run": true in the body of an import, you get the full report — what would be created, updated, left unchanged or refused — and nothing is written. Always check the dry_run field of the response before you trust a report. See Your first API call.

The reference articles