The product data pool API¶
From version 3.8.3
This page describes behaviour available from client version 3.8.3. Sites on an earlier version do not have it yet.
On a product data pool, a merchant's or buying group's own systems (a webshop, an ERP, a partner's platform) can read the product data the organisation has access to through the pool API. The API gives exactly what the organisation sees on screen, and nothing more:
- published products only (see Publishing);
- only the suppliers, and their ranges or brands, that have given the organisation access;
- without the parts of the record a supplier's grant leaves out;
- with prices only where the supplier shares them.
A buying group's own business (deal and rebate references) is never part of an answer. The API is read-only: product data is changed by its supplier.
The address is https://<pool address>/pool-api/v1/. The description of
every call, in OpenAPI 3 form, is at /pool-api/v1/openapi and needs no
sign-in.
On a site that is not a pool¶
The same API, scheduled exports and webhooks are on every site, not only pools. A site that is not a pool publishes nothing and its suppliers grant nothing, so the rules are simpler:
- An organisation (a merchant or group that is a company on the site) can use the API once the site's own staff have set it to Approved on PIM → Access → Organisations. Until then its users see a message saying it has not been switched on. Suspended stops its clients and schedules at once. To approve many at once, narrow the list (Not registered, Current only, and the two name boxes: contains, does not contain), press Tick all shown, then Approve ticked. Current means the company is active and has not left.
- An approved organisation reads the site's products as they are now: every supplier, every field, with prices. This is what its users see on screen.
productsgives the count of matches (total) only for a search by product id, GTIN, product code, supplier or own code. For any other searchtotalis -1: read pages untilnextis 0.changesfollows each product's last-modified date. With no marker it gives nothing and a marker for now: load once with a full file (or by pagingproducts), then followchangesfrom that file's marker. A discontinued product comes as an upsert marked discontinued; a product deleted outright is not reported. There are no access items for suppliers.- A product that has not been indexed yet is left out until it has.
- On the Access page the site's staff see Organisations, API access, Scheduled exports and an Access log of what each organisation took across all suppliers. An approved organisation's users see API access, Scheduled exports and Your product codes.
The older product feed that some merchants call with a signed-in user keeps working unchanged.
API clients¶
Each system that calls the API is an API client with its own client ID and secret. Clients are managed on the Access page, tab API access:
- a merchant or buying group user with the edit role makes, renews and revokes their own organisation's clients;
- pool staff see every client on the pool and can make one for any approved organisation, and set how many requests a minute it may make.
Only an organisation approved for the pool can have clients. Making a client shows its secret once: copy it then, it cannot be shown again. A client can read products, asset files (images and documents), or both.
New secret makes a replacement secret. The old one keeps working for 24 hours so there is time to change the system that uses it. Revoke stops the client at once, including any token it holds. A suspended organisation's clients stop working until it is approved again.
Signing in¶
A client swaps its ID and secret for a token at POST /pool-api/v1/token
(OAuth 2 client credentials), then sends the token with every call as
Authorization: Bearer <token>. A token lasts an hour unless the pool's
settings say otherwise.
Each client has a limit of requests a minute: the pool's setting for new clients (120 by default), or the limit staff gave that client. Every answer says how many are left; past the limit the API answers 429 and says how many seconds to wait.
What can be read¶
| Call | Gives |
|---|---|
products |
Products, 100 a page (up to 500), found by product id, GTIN, supplier part number, supplier, brand, ETIM class or publish date. Discontinued products only when asked for. |
product |
One product, by id, GTIN, or part number with supplier |
changes |
What changed since the last call (see below) |
suppliers |
The suppliers the organisation has access to, with what each grant covers |
template |
The template's attributes: codes, labels, types, units and allowed values |
assets |
One asset file of a product the organisation can see |
exportTemplates, exports, exportFile |
Full files for a first load (see below) |
codes |
The organisation's own product codes; with the codes permission, set or remove them |
A product comes with its record, its template attribute values, its ETIM class and features, its packaging components, its asset list and the organisation's own code for it (see Merchant downloads).
A client reads products and asset files as chosen when it is made. Writing the organisation's own product codes is a separate permission, never given unless chosen.
Staying up to date¶
A system loads everything once with products, then keeps up with
changes. Each answer carries a marker; sending it back next time gives
only what changed since. Items are oldest first and are one of:
- upsert: a product was published or republished; the item carries it;
- delete: a product was withdrawn, deleted or is no longer visible to the organisation; remove it;
- access: the organisation's access to a supplier changed. With
grantedtrue, reload that supplier withproducts; with false, remove its products. Supplier 0 means the organisation itself was approved or suspended.
When an answer says more, call again straight away with the new marker.
While paging, an access item can come more than once; applying it twice is
harmless. A change shows up from the second after it is made.
Full files¶
For a first load of a large catalogue, a system can ask for a full file
instead of paging through products. The file is made by the same export as
Download on the product search screen, with one of the pool's export
templates (exportTemplates lists them) and in that template's format
(Excel, CSV, JSON or XML). It holds what the organisation can see, with the
same access rules; it can be limited to one supplier.
The file is made in the background: exports says when it is ready, then
exportFile gives it. Each file comes with a marker: sending that marker to
changes afterwards picks up whatever changed while the file was being made.
Files are kept for 48 hours, and an organisation can ask for 20 files a day,
unless the pool's settings say otherwise (0 files a day switches full files
off). A client can have one file being made at a time. Making a file counts
its rows in the supplier's access log.
Webhooks¶
A webhook tells an organisation's system when something changes, within about a minute, so it does not have to keep asking. Webhooks are set up on the same API access tab, by the same people as API clients: an https address, the events wanted, and a description. An organisation can have up to five, unless the pool's settings say otherwise. Webhooks only work once they are switched on in the pool's settings.
The events are: product published, changed, discontinued or withdrawn; an
file on a product replaced by a new version; access to a supplier granted or withdrawn; a new
template version published. A webhook only hears about products and files
the organisation can see, exactly as changes would give them.
- Events carry ids and times only; the system reads the data with the API. Up to 100 events go in one post, oldest first.
- Each post is signed with the webhook's secret, shown once when the webhook is made (New secret replaces it at once). The API description says how to check the signature.
- A post that fails is tried again after 1, 5, 15 and 60 minutes, then 3, 6, 12 and 24 hours, then given up (the pool's settings can allow fewer tries). Later posts wait for it, so the order holds. Posts lists them; a given-up post can be sent again with Try again.
- A webhook that keeps failing for 72 hours (or the pool's setting) is switched off and the organisation's users are told. Change switches it back on, and everything that waited is sent; nothing is lost.
- Send test posts a ping and shows what the address answered.
Webhooks only go to public https addresses.
Pool API settings¶
Site administrators set the limits in Site Settings → PIM → Pool API and press Save Settings. On a site that is not a pool the section is called Product API. An empty box means the default:
| Setting | Default | Range |
|---|---|---|
| Requests a minute for a new client | 120 | 10 to 1200 |
| A sign-in token lasts (minutes) | 60 | 5 to 1440 |
| Full files a day per organisation | 20 | 0 (off) to 500 |
| A full file is kept for (hours) | 48 | 1 to 720 |
| Send webhooks | off | on or off |
| Webhooks per organisation | 5 | 1 to 50 |
| Tries after a failed post | 8 | 0 to 8 |
| Switch a webhook off after failing for (hours) | 72 | 1 to 720 |
| Send scheduled exports | off | on or off |
| Scheduled exports per organisation | 5 | 1 to 50 |
| Largest file sent by email (MB) | 10 | 1 to 25 |
A value outside its range stops the save with a message saying which one. While webhooks are switched off, nothing is sent and no webhooks can be added; posts that were waiting go once they are switched back on. A changed limit applies from the next request; a token keeps the lifetime it was given.
The access log¶
Products read through the API count in the supplier's access log as "rows pulled by API", and asset files as "files opened".