Connect your shop to your other systems
The E-commerce API lets your own tools fill your shop and read it back.
Which API is available
- E-commerce API
A JSON over HTTPS API for the shop you run with Ultineo E-commerce. A migration script, an ERP sync or a supplier feed sends records in batches, and reads any single record back to check what was saved.
- Ultineo SaaS project API
An option of an Ultineo SaaS project, not a part of every application. Its availability and its price appear in the offer of the project, and it exposes the operations agreed for that project.
What the API covers
Each subject below is an article of the reference.
- Your first API call
The base URL, the Bearer key and its scopes, a complete curl example, and the batch import contract that every endpoint shares.
- Error codes
The error envelope, every HTTP status the API returns with what to do about it, and how refusals inside an import batch are reported.
- Catalogue
Import and read back your characteristics, categories, product groups, products and customer reviews, in batches and without retyping.
- Orders & logistics
Import your sales history with its original dates, then read each record back: customers, orders, payments, shipments, carrier claims, refused parcels, refunds, returns, wallet movements and support requests.
- Vouchers
Import your discount vouchers and their codes in batches, then read back one voucher with all its codes and their usage counts.
- Parcels, addresses and carriers
Follow parcels from your own software, keep your address book in step and read the carrier catalogue.
How access works
A key is created in the workspace by an administrator of the project: open the project, then the "API Access" tab, and click "Create an API key".
The full value of the key is shown once, when the key is created, and cannot be shown again. Copy it at that moment. If you lose it, delete the key and create another.
A key belongs to one shop. Every read and every write is limited to that shop.
When you create the key, you choose "Full access" or "Restricted access". A restricted key is limited, resource by resource, to reading or to reading and writing.
You also choose its expiry: "30 days", "90 days", "365 days" or "Never expires". Access and expiry are chosen once. To change them, create a new key and delete the old one.
A key needs an open shop: it is created inside the project of the shop, and a key whose shop is no longer active is refused.
The address https://api.ultineo.com/health needs no key: call it to check that the API is reachable.
A typical connection: an ERP
Your catalogue often already exists elsewhere, in an ERP for example. Records refer to each other, so the reference recommends importing first the records that the others depend on.
1. Import the catalogue: characteristics, then categories, then product groups, then products, then reviews.
2. Import the sales history: customers, then orders, then payments and shipments, then refunds, returns, carrier claims, refused parcels, wallet movements and support requests.
3. Import the vouchers, once the customers their codes are reserved for are imported.
Sending a record that is already in your shop updates it or reports it as unchanged. It is never created twice, so you can replay an interrupted import from the beginning.
Each of these resources is read back one record at a time: there is no list and no search.
Before you build
- Address and health check
Every request goes to https://api.ultineo.com/v1/ and only HTTPS is served. The address https://api.ultineo.com/health needs no key and lets you check that the API is reachable.
- Answer envelope and error codes
Every endpoint answers with the same three keys, on success and on failure alike: code, title and response. Read the HTTP status code first, then response, and base your logic on the status code.
- Limits and testing
When too many requests arrive in a short time, the call is refused and the Retry-After header gives the number of seconds to wait. To test an import, send it with dry_run set to true: you get the full report of what would be created, updated, left unchanged or refused, and nothing is written.
Open your shop, then connect it
A key is created inside an open shop. Accounts are opened after a review: send your application, and our team replies by e-mail.
Questions from developers
An administrator of the project of your shop creates it in the workspace, on the "API Access" tab. Its full value is shown once, so copy it when it is created. You need an open shop first, and accounts are opened after a review.
Yes, for imports. Send the batch with dry_run set to true: you get the full report of what would be created, updated, left unchanged or refused, and nothing is written. Check the dry_run field of the response before you trust a report.
The catalogue, the sales history, vouchers, and parcels, addresses and carriers. The article "Your first API call" lists every resource with its scopes. Do not assume that every screen of the workspace has an equivalent endpoint.
A failed call uses the same envelope as a successful one: read the HTTP status code, then the message in response. In an import, each item is checked on its own: an item that fails a check is reported as refused with what to correct, and the other items of the batch carry on.
Yes. Each resource has its own batch limit, given in its reference article, and a request body has a maximum size. When too many requests arrive in a short time, the call is refused and the Retry-After header gives the number of seconds to wait. Sending the same batch again never creates a duplicate.
No. The API provides building blocks, not an automatically installed connector. Your technical team or your service provider builds and tests the exchange against the documented endpoints.
A project API is an option of an Ultineo SaaS project. Its availability and its price appear in the offer of the project, and an application can operate without it. Its reference belongs to the project for which it is activated.
In the E-commerce help center, in the section on the E-commerce API. It is public, written in English and in French, and you need no account to read it.