Products
SKUU reads the catalogue from the store's API, every 12 hours by default, and uses it to link the store's products to the network, to show availability and to route orders. Each read is a complete snapshot. Only a snapshot that validates from the first page to the last counts.
SKUU calls GET /products
GET /productsGET {your_api_root}/products?limit=100
GET {your_api_root}/products?limit=100&cursor=<the next_cursor from the previous page>limitis required and SKUU sends 100 per page; support any value from 1 to 250 and never return more items than asked.- Return
next_cursorwhile there are more pages. Returnnullon the last page. A cursor is opaque; SKUU sends it back as a string. - Keep the snapshot stable while SKUU pages through it.
- Returning
nullearly ends the snapshot early. Every variant missing from a completed snapshot is retired and its network stock set to zero. To remove a product, stop returning it.
The full page shape, with an example, is on Read products.
What a product looks like
A product holds what its variants share. A variant is one sellable choice with its own identifier, price and stock per location.
All product fields
| Product field | Required | What it means |
|---|---|---|
product_id | Required | The store's stable product identifier, unique across the whole catalogue. |
title | Required | Shown to reviewers and in the dashboard; part of the fallback route to link an article. |
brand | Required | SKUU links articles within a brand and shows it everywhere. |
images | Required, at least one | Public HTTPS URLs, primary image first. A person at SKUU opens the image in a browser when two articles look alike, so it must load without an IP allowlist. SKUU stores the first four URLs and never downloads the files. |
category | Optional | Stored and shown; not used to link articles. |
description | Optional | Stored and shown. |
tags | Optional | Two tags change behaviour, see below. Other tags are stored and ignored. |
options | Optional | The names the store's variants vary by, for example ["size", "colour"]. |
variants | Required, at least one | Every sellable variant of this product. |
All variant fields
| Variant field | Required | What it means |
|---|---|---|
variant_id | Required | The identifier SKUU uses in stock events, shipping orders and tracking. Unique across the whole catalogue. |
size | Required | Part of the fallback route to link an article, and shown to reviewers. Use exactly One size for an article without a size; SKUU compares sizes literally, so keep the spelling identical across products. |
price | Required | The consumer price per unit, VAT included. Used for price protection when routing and for the payout. |
currency | Required | ISO 4217 code. Must be the currency on the environment sheet; a different value rejects the whole snapshot. |
inventory | Required | Absolute stock per location: one entry for every agreed physical location and one for SKUU_Network, zeros included. SKUU_Network stays 0 until SKUU writes it. Location ids are whole numbers written as strings. |
barcode | Optional, strongly recommended | EAN or GTIN. The one field that links an article with certainty. Send it wherever it exists and never invent one. |
sku | Optional | The store's internal article code. Second route to link an article when there is no barcode. |
colour | Optional | Stored and shown to reviewers; not used to link articles. |
material, weight_grams | Optional | Stored and shown. |
tax_rate, taxable | Optional | Whether VAT applies. The VAT rate on a network order comes from the delivery country, not from these fields. |
How SKUU links the store's products
SKUU links each of the store's variants to the same article at other shops. It tries the barcode first, then the SKU, then the title and size within the same brand. A catalogue with barcodes links almost completely; a catalogue without barcodes links only where title and size are identical across shops.
Two tags a store can use
SKUU_Excludeon a product keeps its physical stock out of the network.SKUU_Stopon a product keeps network stock from being added to it.
Tags are matched after trimming, case-insensitively.
What makes SKUU reject a snapshot
A missing brand, image or size, a currency that differs from the store's, a duplicate product_id or variant_id, a product without variants, a variant without a barcode, SKU or title and size, a variant missing an agreed location or listing an unknown one, a location id that is not a plain whole number, or a number sent as a string. A rejected snapshot changes nothing; the previous one stays in force. Run the catalogue check with SKUU before the first sync and after every catalogue change.
The next page is Inventory. The exact contract is on Read products.
Updated 22 days ago