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.
Ultineo Logistics help center: parcels, addresses and carriers
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.
- Security
How keys, encrypted connections and team access protect what your integration reaches.
- Service status
The current state of our services
- Product updates
What changed in the products
- Developer help
Where a developer or an integrator finds an answer, what to check first and what to send us.
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.