Writing the catalog

The Catalog API runs on https://catalog.api.metty.eu and authenticates with the secret key in the Authorization header.

method	path	behaviour
PUT	/catalog/products	creates a product or replaces it entirely — an omitted field is cleared
PATCH	/catalog/products	changes only the fields you send; a missing product is an error, not a create
DELETE	/catalog/products	removes products from the database and the index

The body of PUT and PATCH is an array of products with no envelope. One batch holds at most 100 products.

Example

curl -X PUT https://catalog.api.metty.eu/catalog/products \
  -H "Authorization: Bearer <SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "sku-1",
      "name": "Príklepová vŕtačka Bosch",
      "url": "https://eshop.sk/vrtacka",
      "price": 129.9,
      "list_price": 159.9,
      "currency": "EUR",
      "in_stock": true,
      "brand": "Bosch",
      "category": "Náradie > Vŕtačky",
      "description": "Príklepová vŕtačka s reguláciou otáčok.",
      "image": "https://eshop.sk/media/vrtacka.jpg",
      "params": { "farba": "modrá", "príkon": "800 W" }
    }
  ]'

id is your own product identifier and the only required field for PATCH and DELETE. PUT additionally requires name and url.

Fields

field	type	limit	meaning
id	string	1–255	product identity (your SKU)
name	string	255	product name
url	string	2048	link to the product detail
price	number	—	price as a JSON number, not as a string
list_price	number / null	—	price before a discount; a value lower than or equal to price is ignored
currency	string	8	catalog currency (for example EUR) — a property of the catalog, not of the product
in_stock	boolean / null	—	availability
brand	string / null	255	brand
category	string / null	512	category path, levels separated by >
description	string / null	65,535	description
image	string / null	255	image URL
params	object / null	name 128, value 2048	custom attributes — your source of facets

Longer text is not rejected, it is truncated to the limit shown. Watch out for image: a long signed URL may not fit. The only exception is a name in params: one longer than 128 characters is rejected as invalid_params.

params is a map of name to scalar value ({"farba": "modrá"}). You then filter by it in the Search API with farba=modrá, and the widget builds the filters in the Pro and Max templates from it. Booleans are converted to "true" / "false"; null and nested objects are not accepted.

Everything you want to filter by belongs in params

Facets are built from params. If you need a filter by brand or another field of your own, send it as a parameter too — the brand field itself is not filterable.

On top of what you send, Metty can add facets derived from product texts and switch individual facets off per category. That layer is configured on our side and never changes your data: an export returns exactly the params you wrote, while search may offer more fields than that. The same holds for image: the export returns the URL you sent us.

category is the full path from the root; missing levels are created. Both > and | are accepted as separators.

You host the original images; we fetch each one once, keep a 500 px WebP copy and serve the width search asks for. The fetch runs in the background, so a PUT does not wait for it and the product's image in search results stays null for a short while after the first write.

Deleting

curl -X DELETE https://catalog.api.metty.eu/catalog/products \
  -H "Authorization: Bearer <SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["sku-1", "sku-2"]}'

The limit of 100 items per batch applies here as well.

Response

A batch always returns 200 together with the status of every product. One invalid product does not affect the others, and a product that fails validation is not written to the database even partially.

{
  "results": [
    { "id": "sku-1", "status": "ok" },
    { "id": "sku-2", "status": "error", "error": "missing_name", "message": "The field \"name\" is required." }
  ]
}

Always inspect results — a 200 status code does not mean every product went through.

The whole batch fails (4xx without results) only on a wrong key, invalid JSON, more than 100 products, or the wrong catalog mode. The codes are listed under Errors and limits.

Resending

All three operations write by id, so resending the same batch is safe: PUT writes the same values again, PATCH sets the same fields again. No idempotency key is needed. The only difference is DELETE — a repeat returns not_found for products the first attempt already removed.

Bulk changes

There is no separate bulk endpoint. Send the change for multiple products as a PATCH batch; if you do not know their identifiers, take them from the export or from the Search API with the same filter.

A complete synchronisation script is in the examples.