Send your catalogue, sales history and vouchers by API
The API of Ultineo E-commerce takes your catalogue, your sales history and your vouchers in batches, then reads each record back one at a time. This page goes through them resource by resource: what a program sends, what it reads back and the size of a batch.
What a program can do with these resources
- Send the catalogue
Your catalogue often already exists elsewhere, in an ERP, a supplier file or a former shop. The catalogue endpoints let your tools send it to your shop in batches: characteristics, categories, product groups, products and customer reviews.
- Bring the sales history
A migration or sync tool brings your sales history into your shop, from customers and orders to refunds, returns and support requests, keeping the original dates. Every record is recognized by its external_id, so sending it again updates it instead of creating a duplicate.
- Keep your vouchers working
Import your running vouchers and the codes you have already sent, so that they keep working in your shop. Then read each voucher back with all its codes, including how many times each code has been used.
The resources, one by one
Each resource has one path: a POST takes a batch of items, and a GET reads one record back, named by its key or by its identifier in your shop. A GET needs the :read scope of the resource and a POST its :write scope.
- Characteristics
Send up to 25 characteristics per batch, such as a capacity or a color, each of which can carry a closed list of up to 400 values. Read one back by its name or its identifier; the characteristics shared by the service are returned with shared set to true and cannot be written.
- Categories and product groups
Send up to 50 categories per batch, nested through parent with parents sent before their children, and up to 50 product groups, each with up to 20 axes a buyer picks from on the product page. Both are recognized by their name and read back by name or by identifier.
- Products
Send up to 40 products per batch, each recognized by its SKU, with its condition grades, its characteristics and photos that are already in your media, since the API does not upload files. The read by SKU or by identifier returns the product’s own fields, without its grades, characteristics and photos.
- Customer reviews
Send up to 250 reviews per batch from the history of your former shop, each linked to an imported customer and, optionally, to the order it came from. Read one back by its external_id or its identifier; a withdrawn review is still returned, with the status deleted.
- Customers
Send up to 200 customers per batch, each a buyer of your shop with a billing and a delivery address; import them first, because every other record of the sales history refers to them. The read never returns the password itself: has_password says whether one is set.
- Orders and payments
Send up to 100 orders per batch, each with all its lines in one item; totals are stored as you send them, never recalculated, and the report tells you about a mismatch in amount_check. Send up to 300 payments per batch, each settling an imported order, and read an order or a payment back by its external_id or its identifier.
- Shipments, carrier claims and refused parcels
Send up to 500 shipments per batch, each a parcel sent for an imported order with its carrier and tracking number, then up to 500 carrier claims and 500 refused parcels, each tied to an imported shipment. A shipment read back carries a status that follows its dates: delivered, shipped or pending.
- Refunds, order returns, customer wallet and support requests
Send per batch up to 400 refunds, 300 order returns, 500 loyalty wallet movements or 25 support requests, each on its own path; a support request is sent with its thread of messages. Each record is read back by its external_id or its identifier in your shop, and a support request comes back with its thread in date order.
- Vouchers
Send up to 50 vouchers and 500 codes per request: a percentage or a fixed amount off the basket, with an optional minimum amount and validity period, and the codes your customers type at checkout. Read one voucher back with all its codes and their usage counts; the read needs the promotion:read scope and the import promotion:write, although the path is /v1/voucher/import.
An import and its read back
The first sample imports one shipment of an order already imported; the second is the answer when that shipment is read back by its external_id. The second is cut where a line holds only three dots.
Import request
curl https://api.ultineo.com/v1/shipment/import \
-H "Authorization: Bearer sk-project-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"external_id": "SHP-20931",
"order_external_id": "ORD-10458",
"carrier_name": "Colissimo",
"tracking_number": "6A23456789012",
"recipient_name": "Claire Martin",
"shipped_at": 1781334000,
"delivered_at": 1781431200
}
]
}' The shipment is recognized by its external_id and names its order by order_external_id; its dates are Unix timestamps in seconds.
Read-back answer
{
"code": 200,
"title": "OK",
"response": {
"id": "ship_9c1e5a7f02d34b86e0a3",
"object": "shipment",
"external_id": "SHP-20931",
"status": "delivered",
"order": "ordr_5e0a8c2f71d94b36e1c8",
"carrier_name": "Colissimo",
"tracking_number": "6A23456789012",
...
"shipped_at": 1781334000,
"delivered_at": 1781431200,
"created_at": 1781334000,
"updated_at": 1791745200
}
} The answer carries the identifier of the shipment in your shop, ship_…, and the status delivered, since delivered_at is set.
What to watch for
- Child lists are whole sets
When an item carries a child list, such as the values of a characteristic, the axes of a group or the grades and media of a product, that list is the whole set and the entries you left out are deactivated. Leave the list out to keep the stored set untouched.
- Two pages to open once
If your shop has never opened its Claims page or its Refused page, the import of carrier claims or of refused parcels answers 422. Open that page once in your workspace, then replay the batch.
- One code refuses its voucher
An invalid code refuses its whole voucher, and a code already held by another code of the shop refuses it with code 409. Correct the code or choose another one, then send the voucher again.
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
- Products
Product records, images and categories
- Orders
Items, payments and shipments together
- Promo codes
Codes, validity dates and usage limits
- Import & export
Make bulk catalogue changes with a readable result
Continue in this section
- E-commerce API
Create API access and exchange your shop data
- Parcels, addresses and carriers
The Ultineo Logistics API: follow parcels, keep an address book in step and read the carrier catalogue.
- Ultineo Reasoning API
Run your reasoning from your software.
- Ultineo SaaS project API
Review an API scope for an eligible project and distinguish planned routes from the endpoints already built.
Import one resource and you know how to import them all
The reference gives each resource its fields, its batch limit and its examples.
Questions
No. A characteristic, a category and a product group are recognized by their name: a changed name is read as a new record, not as a rename. A product is recognized by its SKU, and a review or a record of the sales history by its external_id.
No endpoint of these resources deletes a record: deleting is done in your workspace. A record withdrawn there keeps its status: an import never brings it back, and a notice says so. For a review or an order return, sending the status deleted withdraws a record already imported.
Yes. The created_at you send is kept as the original date of the record and is never changed by a later import. Dates are Unix timestamps in seconds, and when you leave created_at out, most resources use the closest date they know, such as the date of the order.
Only percentage and fixed-amount vouchers are imported. Free shipping, gifts, product or segment targeting and the history of each use of a code are managed in your workspace and are not available through the API. The API does not delete a voucher or a code either.