# Create or update products

> POST /api/v0/products: send new and changed products to Releva, with variants, languages, currencies and markets, custom fields, a field table, a working curl, responses, errors and limits.

`POST /api/v0/products` creates the products you send, or updates them when Releva already has them. It is the main way Releva learns about changes in your catalog.

## When to use it

Call it whenever your catalog changes: a new product, a new price, a product that goes out of stock or comes back in stock. This is the primary way Releva learns about changes in your catalog. Platform plugins already call it for you; you need it when your shop is custom-built.

* To change only `available`, [Update product availability](https://releva.ai/documentation/reference/catalog/update-product-availability/) is lighter.
* To remove a product for good, use [Delete a product](https://releva.ai/documentation/reference/catalog/delete-a-product/). A product that is only out of stock stays in the catalog with `available: false`.
* As a safety net for changes you miss, also build the endpoint described in [Let Releva pull your catalog](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/).

## Authentication

Send your shop’s **Secret Key** as a bearer token: `authorization: Bearer $RELEVA_SECRET_KEY`. Never use it in a browser or an app. Find it under **Settings › Shop & Integration** ([Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/)). The error messages are in [Catalog API: Authentication](https://releva.ai/documentation/reference/catalog/overview/#authentication).

## Request

`POST https://releva.ai/api/v0/products` with `content-type: application/json` and a body `{ "products": [ ... ] }` that holds at least one product. The maximum body is 800 KB: split larger catalogs into several requests, a few hundred products per request.

The example sends one product in its UK English version, on sale, with every common field. For variants, see [Variants](https://releva.ai/documentation/reference/catalog/create-or-update-products/#variants).

```plaintext
curl -X POST 'https://releva.ai/api/v0/products' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "products": [
      {
        "id": "DEMO-1001_en_uk",
        "name": "Linen Summer Shirt",
        "description": "A breathable linen shirt for warm days.",
        "locale": "en",
        "currency": "GBP",
        "listPrice": 39.90,
        "discountPrice": 29.90,
        "stockQuantity": 25,
        "sku": "DEMO-1001-M",
        "categories": ["Men/Shirts", "Summer"],
        "available": true,
        "url": "https://demo-store.example.com/uk/products/linen-summer-shirt",
        "canonicalUrl": "https://demo-store.example.com/products/linen-summer-shirt",
        "imageUrl": "https://demo-store.example.com/images/linen-summer-shirt.jpg",
        "publishedAt": "2026-05-01T09:00:00Z",
        "marketHandle": "uk",
        "markets": ["GB"],
        "data": { "badge": "New in" },
        "custom": {
          "string": [
            { "key": "brand", "values": ["Demo Basics"] },
            { "key": "color", "values": ["white", "sand"] }
          ],
          "numeric": [{ "key": "size", "values": [38, 40, 42] }],
          "date": [{ "key": "promoUntil", "values": ["2026-11-01T00:00:00Z"] }]
        },
        "inventory": [
          { "location": [{ "lat": 42.6977, "lon": 23.3219 }] }
        ]
      }
    ]
  }'
```

### Product fields

A product is validated strictly: a key that is not in this table is rejected. Put extra data in `custom` or `data`.

| Field                        | Type             | Required | Notes                                                                                                                                                                                                                                             |
| ---------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                         | string           | yes      | Identifies the stored product in your shop. One id per language and market; see [Languages, currencies and markets](https://releva.ai/documentation/reference/catalog/create-or-update-products/#languages-currencies-and-markets). [Delete a product](https://releva.ai/documentation/reference/catalog/delete-a-product/) takes the same id. |
| `name`                       | string           | yes      |                                                                                                                                                                                                                                                   |
| `listPrice`                  | number           | yes      | The regular price, 0 or more.                                                                                                                                                                                                                     |
| `categories`                 | array of strings | yes      | Category paths separated by `/`, for example `"Men/Shirts"`. May be empty.                                                                                                                                                                        |
| `available`                  | boolean          | yes      | `true` when the product can be bought.                                                                                                                                                                                                            |
| `description`                | string           | no       |                                                                                                                                                                                                                                                   |
| `locale`                     | string           | no       | ISO-639-1 language code (`en`, not `en-US`). Default: your shop’s language.                                                                                                                                                                       |
| `currency`                   | string           | no       | ISO-4217 code (`EUR`). Default: your shop’s currency.                                                                                                                                                                                             |
| `discountPrice`              | number           | no       | If the product is on sale, the sale price, 0 or more. It must be lower than `listPrice` (a higher one is accepted but stores a negative discount). If the product is not on sale, do not include this field.                                      |
| `stockQuantity`              | integer          | no       | Units left, 0 or more.                                                                                                                                                                                                                            |
| `sku`                        | string           | no       | The SKU of the product, or of the variant shoppers see first.                                                                                                                                                                                     |
| `url`                        | string           | no       | Absolute URL of the product page, as a shopper in this language and market sees it.                                                                                                                                                               |
| `canonicalUrl`               | string           | no       | Absolute URL without a language or market prefix. Ad catalog feeds use it as the base link; without it they use `url`.                                                                                                                            |
| `imageUrl`                   | string           | no       | Absolute image URL. Default: your shop’s default product image.                                                                                                                                                                                   |
| `publishedAt`                | string           | no       | When the product went on sale. ISO-8601 with seconds and a zone: `2026-05-01T09:00:00Z`, `2026-05-01T09:00:00.000Z` or `2026-05-01T12:00:00+0300`.                                                                                                |
| `marketHandle`               | string           | no       | Your name for the market this product belongs to, for example `uk`. See [Languages, currencies and markets](https://releva.ai/documentation/reference/catalog/create-or-update-products/#languages-currencies-and-markets).                                                                                                   |
| `markets`                    | array of strings | no       | ISO-3166-1 alpha-2 country codes in upper case (`["FR", "DE"]`). Anything else is rejected.                                                                                                                                                       |
| `groupId`                    | string           | no       | The product all versions of this product belong to. Used only together with a non-empty `variants`. See [Variants](https://releva.ai/documentation/reference/catalog/create-or-update-products/#variants).                                                                                                                    |
| `variants`                   | array of objects | no       | One entry per variant. See [Variants](https://releva.ai/documentation/reference/catalog/create-or-update-products/#variants).                                                                                                                                                                                                 |
| `custom`                     | object           | no       | Custom fields to filter, group and personalize on. See [The custom object](https://releva.ai/documentation/reference/catalog/create-or-update-products/#the-custom-object).                                                                                                                                                   |
| `data`                       | object           | no       | Any JSON you want back with the product in product block responses, for example `{ "badge": "New in" }`. Releva does not search or filter on it.                                                                                                  |
| `inventory`                  | array of objects | no       | Stock locations: `[{ "location": [{ "lat": 42.6977, "lon": 23.3219 }] }]`.                                                                                                                                                                        |
| `inventory[].location[].lat` | number           | no       | Latitude of the location in decimal notation, for example `42.6977`.                                                                                                                                                                              |
| `inventory[].location[].lon` | number           | no       | Longitude of the location in decimal notation, for example `23.3219`.                                                                                                                                                                             |

The body can also carry `deleteMissingVariants` (boolean) next to `products`. It is deprecated: it is accepted for older integrations and has no effect. Remove variants you no longer sell from the `variants` array, and remove products you no longer sell with [Delete a product](https://releva.ai/documentation/reference/catalog/delete-a-product/).

## Variants

Send one product per product page and describe its variants in `variants`. The product keeps what is shared (name, description, categories, URL); each variant carries what differs. New integrations should prefer the `variants` array: it keeps one entry per product page in recommenders and search instead of one entry per variant, and the Meta catalog sync uses it to build variant-level catalog items.

| Variant field   | Type             | Required | Notes                                                            |
| --------------- | ---------------- | -------- | ---------------------------------------------------------------- |
| `variantId`     | string           | yes      | Your id for the variant.                                         |
| `sku`           | string           | no       |                                                                  |
| `listPrice`     | number           | no       | 0 or more.                                                       |
| `discountPrice` | number           | no       | 0 or more.                                                       |
| `available`     | boolean          | no       |                                                                  |
| `stockQuantity` | integer          | no       | 0 or more.                                                       |
| `imageUrl`      | string           | no       | Absolute URL, when the variant has its own image.                |
| `barcode`       | string           | no       | GTIN, EAN or similar.                                            |
| `optionValues`  | array of objects | no       | One `{ "name": "Size", "value": "M" }` per option. No other key. |

Rules to know:

* **Send `groupId` and `variants` together.** Without a non-empty `variants`, Releva ignores your `groupId` and uses the product’s own `id`. With `variants` but no `groupId`, the group is the product’s `id`.
* A product sent without `variants` is stored as one variant built from the product itself.
* The product-level `listPrice`, `discountPrice`, `available`, `stockQuantity`, `sku` and `imageUrl` stay the values Releva shows. Set them to the variant a shopper sees first, usually the first available one.
* Use the same `groupId` for every language and market version of one product. The Meta catalog sync uses `groupId`, `variants` and `markets` to build per-variant and per-country items.

```plaintext
curl -X POST 'https://releva.ai/api/v0/products' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "products": [
      {
        "id": "DEMO-1001_en",
        "groupId": "DEMO-1001",
        "name": "Linen Summer Shirt",
        "locale": "en",
        "currency": "EUR",
        "listPrice": 39.90,
        "sku": "DEMO-1001-M",
        "categories": ["Men/Shirts"],
        "available": true,
        "url": "https://demo-store.example.com/products/linen-summer-shirt",
        "variants": [
          {
            "variantId": "DEMO-1001-M",
            "sku": "DEMO-1001-M",
            "barcode": "5901234123457",
            "listPrice": 39.90,
            "discountPrice": 29.90,
            "available": true,
            "stockQuantity": 12,
            "imageUrl": "https://demo-store.example.com/images/linen-summer-shirt-m.jpg",
            "optionValues": [
              { "name": "Size", "value": "M" },
              { "name": "Color", "value": "White" }
            ]
          },
          {
            "variantId": "DEMO-1001-L",
            "sku": "DEMO-1001-L",
            "listPrice": 39.90,
            "available": false,
            "stockQuantity": 0,
            "optionValues": [
              { "name": "Size", "value": "L" },
              { "name": "Color", "value": "White" }
            ]
          }
        ]
      }
    ]
  }'
```

### Sending each variant as its own product (older style)

The older integration style, one Releva product per variant with the parent product id in a `product_id` custom field, is still accepted. Use it only if your integration already works this way.

```plaintext
curl -X POST 'https://releva.ai/api/v0/products' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "products": [
      {
        "id": "DEMO-1001-M",
        "name": "Linen Summer Shirt",
        "locale": "en",
        "currency": "EUR",
        "listPrice": 39.90,
        "categories": ["Men/Shirts"],
        "available": true,
        "url": "https://demo-store.example.com/products/linen-summer-shirt",
        "imageUrl": "https://demo-store.example.com/images/linen-summer-shirt.jpg",
        "publishedAt": "2026-05-01T09:00:00Z",
        "custom": {
          "string": [
            { "key": "product_id", "values": ["DEMO-1001"] },
            { "key": "size", "values": ["M"] },
            { "key": "color", "values": ["white"] }
          ]
        }
      }
    ]
  }'
```

In this style, [Delete a product](https://releva.ai/documentation/reference/catalog/delete-a-product/) removes one variant at a time, by its own id.

## Languages, currencies and markets

Releva stores one product per `id` in your shop. Nothing else is part of the key: the same `id` with another `locale` overwrites the first version. When you sell one product in several languages or markets, give each version its own `id`. Releva’s own connectors use:

```plaintext
{yourProductId}_{locale}            for example DEMO-1001_en
{yourProductId}_{locale}_{market}   for example DEMO-1001_en_uk
```

On every version, set:

* `locale` and `currency`. Left out, they fall back to your shop’s defaults, not to the stored value.
* `groupId`, the same on all versions, together with `variants`.
* For a catalog split by market: `marketHandle`, `markets`, and `canonicalUrl` next to the market’s own `url`.

When the page push carries `page.market`, product blocks show only products whose `marketHandle` matches it, and Search As You Type shows products with that `marketHandle` or with none.

## The custom object

Custom fields are what you filter, group and personalize on: brand, color, material, a promotion end date. They are grouped by value type; each entry is a `key` with a list of `values`. No other key is allowed.

| Field            | Values                                  | Example                                                       |
| ---------------- | --------------------------------------- | ------------------------------------------------------------- |
| `custom.string`  | strings                                 | `{ "key": "color", "values": ["white", "sand"] }`             |
| `custom.numeric` | numbers                                 | `{ "key": "size", "values": [38, 40] }`                       |
| `custom.date`    | dates; a plain `2026-11-01` is accepted | `{ "key": "promoUntil", "values": ["2026-11-01T00:00:00Z"] }` |

Releva adds `category_level_1`, `category_level_2` and so on to `custom.string` from your category paths. Do not send them.

If **Product Custom Fields To Sync** is set to **Specific** under **Settings › Shop & Integration › Catalog Sync**, only the listed custom keys are stored. Other keys are dropped without an error, from API pushes as well as from syncs.

## Sending updates

Each call updates the products it contains and leaves the rest of your catalog untouched. Within a product, always send the **complete** object rather than only the fields that changed. A partial product loses data:

| Left out             | What happens                                                                                                                                         |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `discountPrice`      | Cleared. That is how you take a product off sale.                                                                                                    |
| `custom`             | Replaced by what you send (only the listed keys when **Product Custom Fields To Sync** is **Specific**); left out, the product has no custom fields. |
| `variants`           | Replaced by what you send; left out, the product falls back to one variant built from itself.                                                        |
| `locale`, `currency` | Reset to your shop’s defaults.                                                                                                                       |

The required fields must be in every request, even for an update.

Releva compares each price and availability with the stored product. A change is recorded as a catalog event (price drop or rise, back in stock, out of stock), which [catalog triggers](https://releva.ai/documentation/learn/catalog-triggers/how-catalog-triggers-work/) use. Sending the same payload twice does not trigger a campaign again.

## Response

`202 Accepted` with the body `{}`. The products are queued, not yet stored: they are usually searchable within about 10 seconds. Check them under **Data Platform › Products**.

## Errors

Errors have one shape, `{ "message": "..." }`. When several fields fail, the messages are joined with a space.

| Status | When                             | Message                                                                                                                                                                                                                                        |
| ------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Authentication failed            | See [Catalog API: Authentication](https://releva.ai/documentation/reference/catalog/overview/#authentication)                                                                                                                                                   |
| `400`  | Empty `products`                 | `The 'products' field must contain at least 1 items.`                                                                                                                                                                                          |
| `400`  | Numeric `id`                     | `The 'products[0].id' field must be a string.`                                                                                                                                                                                                 |
| `400`  | Unknown key `color` on a product | `The object 'products[0]' contains forbidden keys: 'color'.`                                                                                                                                                                                   |
| `400`  | `stockQuantity: 1.5`             | `The 'products[0].stockQuantity' field must be an integer.`                                                                                                                                                                                    |
| `400`  | `locale: "en-US"`                | `products[0].locale must be a valid ISO-639-1 code! Got en-US instead.`                                                                                                                                                                        |
| `400`  | `currency: "EURO"`               | `products[0].currency must be a valid ISO-4217 currency code! Got EURO instead.`                                                                                                                                                               |
| `400`  | `markets: ["de"]`                | `The 'products[0].markets[0]' field fails to match the required pattern.`                                                                                                                                                                      |
| `400`  | `publishedAt: "2026-05-01"`      | `products[0].publishedAt must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-05-01 instead.` |
| `400`  | Relative `url`                   | `The 'products[0].url' field must be a valid URL.`                                                                                                                                                                                             |
| `400`  | Variant without `variantId`      | `The 'products[0].variants[0].variantId' field is required.`                                                                                                                                                                                   |
| `402`  | Your shop is disabled            | `Domain is disabled. Please reach out to support@releva.ai to enable it.`                                                                                                                                                                      |
| `413`  | Body larger than 800 KB          | `request entity too large`                                                                                                                                                                                                                     |
| `500`  | Unexpected error; retry later    | `An internal error occurred.`                                                                                                                                                                                                                  |

## Limits

* Body size: 800 KB per request. Split a large catalog into batches of a few hundred products.
* Rate limits: none.
* Processing: asynchronous, usually within about 10 seconds.

## Next steps

* [How your catalog gets into Releva](https://releva.ai/documentation/learn/catalog/how-your-catalog-gets-into-releva/): Learn how products are identified, merged and made visible after you send them.
* [Update product availability](https://releva.ai/documentation/reference/catalog/update-product-availability/): Change only the stock state of products that are already in Releva.
* [Let Releva pull your catalog](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/): Build the endpoint that keeps Releva’s catalog complete when a change is missed.
* [Find a product in your catalog](https://releva.ai/documentation/guides/catalog/find-a-product/): Check in the admin what Releva stored for a product.