Developers · Resources

Learn the rules shared by every route of the API

The API of Ultineo E-commerce is a JSON-over-HTTPS API whose routes share the same rules. This page gathers them: the answer envelope, the way a record is named, dates, amounts, lists and the version.

What every route has in common

JSON over HTTPS

Every route is served over HTTPS only. A body is JSON, sent with the Content-Type header application/json.

The version in the path

The version of the API is in the path: the routes of the reference are under /v1/. Every request therefore goes to https://api.ultineo.com/v1/.

Two names for a record

A record has two names: the key you gave it, which is external_id, or the SKU or the name for a catalogue record, and its identifier in your shop. A read takes one or the other.

How to read any answer

1

Read the HTTP status

The HTTP status code is the first thing to read, on a success and on a failure alike. The guide "Handle errors and limits" says what each status asks of your client.

2

Open the envelope

Every endpoint answers with the same three keys: code, title and response. A failed call uses the same envelope as a successful one.

3

Identify code and title

The code key repeats the HTTP status code in the body. The title key holds the short label of the status, such as OK or Not Found.

4

Read response

On success, response holds the record or the import report. On failure, it holds a message that describes what went wrong.

The same envelope on success and on failure

The two answers are separate examples of the reference: a category read back, cut to a few fields, and another call, refused for a missing scope. They carry the same three keys.

Successful call

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "category",
    "id": "cate_4be1a07f93c2d58e6a10",
...
    "created_at": 1789143990,
    "updated_at": 1789143990
  }
}

The response key holds the record, and its two dates are numbers of seconds.

Failed call

{
  "code": 403,
  "title": "Forbidden",
  "response": "The API key is missing the required scope: order:write"
}

The response key holds a message in place of a record.

What to watch in dates, amounts and lists

A date in another format

Timestamps, such as created_at, are sent and returned as integer numbers of seconds since the Unix epoch, in UTC, and 0 in a response means that the date is not set. A date in another format is refused, not converted.

Amounts read as numbers

Amounts are returned as strings holding a decimal number, such as "129.90". This form is used so that no precision is lost.

Listing an imported resource

An imported resource has no list: a read returns one record. Lists exist only in the API of Ultineo Logistics (parcels, addresses and carriers): they take limit, 50 by default and 100 at most, and offset.

The articles behind this page

This page restates the following articles of the help center. They hold every field, every value and every answer.

API overview

Your first API call

Ultineo Logistics help center: parcels, addresses and carriers

Error codes

Orders & logistics

Orders

Items, payments and shipments together

Open the page

Product pages to read next

API access

Connect your systems through scoped shop access

Products

Product records, images and categories

Orders

Items, payments and shipments together

Shipments

Parcels, carriers and delivery progress

Continue in this section

E-commerce API reference

Every article of the E-commerce API, in the help center.

Open the page

Security

How keys, encrypted connections and team access protect what your integration reaches.

Open the page

Service status

The current state of our services

Open the page

Product updates

What changed in the products

Open the page

Developer help

Where a developer or an integrator finds an answer, what to check first and what to send us.

Open the page

Developer overview

Apply these rules to your own shop

A key is created inside an open shop, and Ultineo E-commerce accounts are opened after a review of your application.

Questions

A list answers total, limit, offset and data. In the API of Ultineo Logistics, the parcel list can also be synced, to follow changes without reading everything again: its help center gives the calls.

On the routes of parcels, addresses and carriers of the Ultineo Logistics API, an identifier carries a prefix: carr_ for a carrier, parc_ for a parcel, addr_ for an address and ship_ for a dispatch. A carrier, a parcel and an address also name their type in their object field, which always reads carrier, parcel or address.

Yes. In an import, the amount fields, such as the total of an order or the amount of a payment, accept a number or a string. The reference article "Orders & logistics" lists these fields; the amount of a payment, for example, takes up to 2 decimals.

In the sales history, a link to another record uses the external_id of that record: customer_external_id, order_external_id, shipment_external_id, and so on. The record it names must already be imported: the guide "Import in batches" gives the recommended order.