Developers ยท Guides
Import your data in batches and check every item
Every import of the API of Ultineo E-commerce follows the same contract: a list of items, an optional dry run and a line-by-line report. Once you have imported one resource, you know how to import them all.
What to have before your first batch
- A key and its scopes
An import is a POST, which needs the write scope of its resource, and a read is a GET, which needs its read scope. A key is created in the workspace by an administrator of the project of your shop.
- A reference for each record
Each record is recognized by its own key: its reference in your former system (external_id), or its SKU or name for the catalogue. The report returns, for each item, the key it was recognized by.
- Sets cut into batches
Each resource has its own batch limit, from 25 to 500 items, given in its endpoint table. Larger sets are sent as several batches.
From the first batch to a checked import
-
1
Follow the import order Records refer to each other, so import first the records the others depend on: the catalogue, then the sales history, then the vouchers. A record that refers to one not imported yet is refused.
-
2
Build the batch Send a POST to the import path of the resource with an items list, one object per record. The list must not be empty, nor longer than the batch limit of the resource.
-
3
Send a dry run Add dry_run set to true: the whole batch is checked and the report says what would be created, updated, left unchanged or refused. Nothing is written.
-
4
Read the report The data list holds one entry per item, in the order you sent them, with its action: created, updated, unchanged or refused. For a refused item, reason says what to correct.
-
5
Send the real import Send the batch again without dry_run, which defaults to false. A refused item does not stop the others: act on its code and its reason, then send it again.
-
6
Read a record back A GET on the same import path returns one record, named by its key or by its identifier in your shop. Use it to check what was saved.
A dry-run batch and its report
Every import takes the same body and answers with the same report. This dry run of two categories and the report that answers it are published together in the reference article "Catalog".
Dry-run request
curl https://api.ultineo.com/v1/category/import \
-H "Authorization: Bearer sk-project-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"dry_run": true,
"items": [
...
{ "name": "iPhone", "parent": "Smartphones", "position": 1 }
]
}' The body carries dry_run set to true and two categories, the first of which is cut here.
Report of this request
{
"code": 200,
"title": "OK",
"response": {
"object": "list",
"resource": "category",
"dry_run": true,
"data": [
...
],
"created": 1,
"updated": 0,
"unchanged": 1,
"refused": 0,
"total": 2
}
} Its dry_run field reads true, so nothing was written, and its four counters add up to total, the number of items sent.
What to watch in an import
- A 200 with refused items
A refused item never blocks the others: the call answers 200 as soon as at least one item was accepted, and 422 only when every item was refused. Read the report line by line, even on a 200.
- A dry-run report
A dry run returns the full report, as a real import does, and writes nothing. Always check the dry_run field of the response before you trust a report.
- A deleted record
An import does not delete anything, and it never brings a deleted record back. Deleting is done in your workspace.
The articles behind this page
This page restates the following articles of the help center. They hold every field, every value and every answer.
Product pages to read next
- API access
Connect your systems through scoped shop access
- Import & export
Make bulk catalogue changes with a readable result
- Products
Product records, images and categories
- Customers
Customer records, addresses and notes
- Orders
Items, payments and shipments together
Continue in this section
- Make your first API call
The address, the health check, the key in the header and how to read the answer of a first call.
- Manage keys and access
Who creates a key, what it may reach, when it expires and how to rename, disable or delete it.
- Handle errors and limits
What each status of the API asks of your client, and what you can safely send again.
- Connect an ERP or a supplier feed
A typical connection from another system: the keys to map, a first dry run, the sync and its checks.
- Move an existing shop
Bring your catalogue, your sales history and your domain to a new shop, and check each step.
- AI inside your software
A reasoning step added to a screen of your own software, launched through the API and read back.
Open your shop, then send your first batch
A key is created inside an open shop, and accounts are opened after a review of your application by our team.
Questions
Yes, with dry_run set to true. In that report, the id of a record that would be created is null. For a product, its own fields are compared with what is stored, while its grades, characteristics and photos are checked but not compared.
Replay it from the beginning. Sending a record that is already in your shop updates it if something changed, or reports it as unchanged; it is never created twice.
No. An update only changes the fields you sent, and the fields you leave out keep their stored value. A child list of a catalogue record, such as the grades of a product, follows another rule: the page "Catalogue, orders and vouchers" gives it.
Its frame is the same: one entry per item, then the counters. Some resources add their own fields to each entry, such as the lines of an order or the codes of a voucher, and the reference article of each resource describes them. An accepted item may also carry messages in notice, such as a value that was adjusted.