> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

> Create and update products with support for branches, variations, and modifiers.

You can create or update products in bulk by their SKU. If a product with the specified SKU already exists, it is updated; otherwise, it is created. Products can be assigned to a [branch](https://docs.jelou.ai/en/api/shop/branches/create.md), have multiple variations, and modifier groups.

**app\_id** `string` *required*

Your store ID in Jelou Shop.

**resources** `object[]` *required*

List of products to create or update (max. 500 per request).

## Product fields

Each object within `resources` accepts the following fields:

**sku** `string` *required*

Unique product identifier (max. 255 characters).

**name** `string` *required*

Product name (max. 255 characters).

**price** `number` *required*

Product price (min. 0).

**description** `string`

Product description.

**has\_tax** `boolean` (default: true)

Indicates whether the price includes taxes.

**tax** `number`

Individual product tax rate (between `0` and `100`). Example: `15` for 15%, `12` for 12%. Only applies when `enable_per_product_tax` is active in the [store settings](https://docs.jelou.ai/en/api/shop/settings/store.md). If not sent or is `0`, the store's global rate is used.

**status** `boolean` (default: true)

Product status (active/inactive).

**stock\_type** `string` (default: unlimited)

Inventory type: `limited` or `unlimited`.

**stock** `number`

Available quantity. Applies only when `stock_type` is `limited`.

**product\_url** `string`

URL of the product in your store (max. 2048 characters).

**discount\_type** `string`

Discount type: `value` (fixed amount) or `percentage`.

**discount** `number`

Discount value (min. 0).

**categories** `string[]`

List of category names. They are created automatically if they do not exist.

**images** `string[]`

List of public image URLs for the product.

**note\_enabled** `boolean` (default: false)

Enables a note field on the product detail page, allowing the customer to add a comment when adding the product to the cart (e.g., "No onions", "Gift wrap").

**note\_label** `string`

Placeholder text displayed in the note field (max. 255 characters). If not specified, a generic default text is used.

**branch** `string`

Code of the branch to which the product is assigned. The branch must already exist.

> [!WARNING]
>
> The branch must be created before assigning it to a product. Use the [Create branch](https://docs.jelou.ai/en/api/shop/branches/create.md) endpoint to register it first.

**features** `object[]`

List of product features (spec sheet).

**Fields of each feature**

**label** `string` *required*

Feature name (max. 255 characters). E.g., `Material`, `Weight`.

**value** `string` *required*

Feature value (max. 200 characters). E.g., `Cotton`, `500g`.

**replace\_variations** `boolean` (default: false)

Controls how variations are synced. With `false` (default), variations are updated or created by SKU and existing ones not present in the payload are **kept**. With `true`, variations not present in the payload are **removed**.

**variations** `object[]`

List of product variations.

**Variation fields**

**sku** `string` *required*

Unique SKU of the variation (max. 255 characters). If a variation with this SKU already exists, it is updated.

**price** `number` *required*

Variation price (min. 0).

**stock\_type** `string` (default: unlimited)

Variation inventory type: `limited` or `unlimited`. Allows managing stock for each variation independently from the parent product.

**stock** `number`

Available quantity for the variation. Applies only when `stock_type` is `limited`.

**properties** `object`

Additional properties in JSON format.

**images** `string[]`

List of image URLs for the variation.

**attributes** `object[]`

List of variation attributes.

**Attribute fields**

**name** `string` *required*

Attribute name — for example: `Size`, `Color` (max. 255 characters).

**value** `string` *required*

Attribute value — for example: `M`, `Blue` (max. 255 characters).

**modifier\_groups** `object[]`

Product modifier groups (add-ons). Common in food delivery (e.g., "Choose your Drinks", "Pick your Sauces"). If the field is absent, existing modifiers are preserved. If it is an empty array `[]`, all modifiers are deleted. If it has data, modifiers are completely replaced.

**Modifier group fields**

**code** `string` *required*

Unique group code (max. 255 characters).

**name** `string` *required*

Visible group name (max. 255 characters).

**min\_quantity** `integer` (default: 0)

Minimum number of options the customer must select.

**max\_quantity** `integer` (default: 1)

Maximum number of options the customer can select (min. 1).

**max\_per\_option** `integer`

Maximum number of times the same option can be chosen (min. 1).

**is\_required** `boolean` (default: false)

Whether the group is required to add to the cart.

**position** `integer`

Group sort position (assigned automatically if omitted).

**options** `object[]` *required*

List of group options (minimum 1 option).

**Option fields**

**code** `string` *required*

Unique option code (max. 255 characters).

**name** `string` *required*

Visible option name (max. 255 characters).

**price** `number` (default: 0)

Additional price for the option (min. 0).

**image\_url** `string`

Option image URL (must be a public URL).

**position** `integer`

Sort position (assigned automatically if omitted).

**status** `boolean` (default: true)

Whether the option is available.

**linked\_product\_sku** `string`

SKU of a linked product. Resolved to `linked_product_id` (UUID). If the SKU is not found, stored as `null`.

> [!NOTE]
>
> Modifiers are stored on the product and returned automatically in all endpoints that return products.

## Full example

This example creates three products: a t-shirt with size variations, a simple pair of pants, and a pizza with modifier groups.

```bash cURL theme={null}
curl -X POST "https://gateway.jelou.ai/ecommerce/v2/apps/{app_id}/batch/products/upsert_by_sku" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "sku": "TSHIRT-BLU",
        "name": "Basic Blue T-Shirt",
        "description": "100% premium cotton t-shirt, regular fit",
        "price": 29.99,
        "has_tax": true,
        "tax": 15,
        "status": true,
        "stock_type": "limited",
        "stock": 150,
        "product_url": "https://my-store.com/basic-blue-tshirt",
        "discount_type": "percentage",
        "discount": 10,
        "branch": "BRANCH-DOWNTOWN",
        "categories": ["Clothing", "T-Shirts"],
        "images": [
          "https://my-store.com/images/blue-tshirt-front.jpg",
          "https://my-store.com/images/blue-tshirt-back.jpg"
        ],
        "variations": [
          {
            "sku": "TSHIRT-BLU-S",
            "price": 29.99,
            "stock_type": "limited",
            "stock": 50,
            "attributes": [
              { "name": "Size", "value": "S" },
              { "name": "Color", "value": "Blue" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-M",
            "price": 29.99,
            "stock_type": "limited",
            "stock": 60,
            "attributes": [
              { "name": "Size", "value": "M" },
              { "name": "Color", "value": "Blue" }
            ]
          },
          {
            "sku": "TSHIRT-BLU-L",
            "price": 31.99,
            "stock_type": "limited",
            "stock": 40,
            "attributes": [
              { "name": "Size", "value": "L" },
              { "name": "Color", "value": "Blue" }
            ],
            "images": [
              "https://my-store.com/images/blue-tshirt-L.jpg"
            ]
          }
        ]
      },
      {
        "sku": "PANTS-BLK-M",
        "name": "Black Pants",
        "price": 49.99,
        "branch": "BRANCH-NORTH",
        "categories": ["Clothing", "Pants"],
        "note_enabled": true,
        "note_label": "Any special instructions?"
      },
      {
        "sku": "PIZZA-FAMILY",
        "name": "Family Pepperoni Pizza",
        "description": "Family-size pepperoni pizza with artisan crust",
        "price": 18.99,
        "stock_type": "unlimited",
        "branch": "BRANCH-NORTH",
        "categories": ["Pizzas", "Promotions"],
        "images": ["https://example.com/pepperoni-pizza.jpg"],
        "modifier_groups": [
          {
            "code": "drinks",
            "name": "Choose your Drink",
            "min_quantity": 1,
            "max_quantity": 1,
            "is_required": true,
            "options": [
              { "code": "coca-1l", "name": "Coca Cola 1L", "price": 0 },
              { "code": "sprite-1l", "name": "Sprite 1L", "price": 0 },
              { "code": "fanta-1l", "name": "Fanta 1L", "price": 0.50 }
            ]
          },
          {
            "code": "extras",
            "name": "Extra Toppings",
            "min_quantity": 0,
            "max_quantity": 5,
            "max_per_option": 2,
            "is_required": false,
            "options": [
              { "code": "extra-cheese", "name": "Extra Cheese", "price": 1.50 },
              { "code": "ham", "name": "Ham", "price": 2.00 },
              { "code": "olives", "name": "Olives", "price": 1.00 }
            ]
          }
        ]
      }
    ]
  }'
```

```json 200 Success theme={null}
{
  "message": "Batch upsert process initiated successfully",
  "count": 3,
  "jobs": 3
}
```

```json 422 Validation Error theme={null}
{
  "message": "The resources field is required.",
  "errors": {
    "resources": ["The resources field is required."]
  }
}
```

> [!NOTE]
>
> Replace `{app_id}` with your store ID and `YOUR_API_KEY` with your [API key](https://docs.jelou.ai/en/guides/settings/api-keys.md).

## Behavior

> [accordion] Asynchronous processing (default)
>
> The endpoint returns `202 Accepted` immediately. Products are processed in the background.

> [accordion] Synchronous processing (X-Sync)
>
> Send the `X-Sync: true` header to process synchronously and receive the per-product result in the same response (`200 OK`). In this mode the maximum is **50 products** per request.
>
> ```json 200 OK theme={null}
> {
>   "message": "Batch upsert processed synchronously",
>   "count": 2,
>   "succeeded": 1,
>   "failed_count": 1,
>   "failed": [
>     { "sku": "CAM-BLU", "status": "failed", "error": "..." }
>   ],
>   "results": [
>     { "sku": "PAN-NEG-M", "status": "success" },
>     { "sku": "CAM-BLU", "status": "failed", "error": "..." }
>   ]
> }
> ```

> [accordion] Non-existent branch
>
> If the branch code does not match any branch in the store, the product is created without a branch assignment. No error is produced.

> [accordion] Automatic categories
>
> If a category does not exist, it is created automatically within the store and the corresponding branch.

> [accordion] Asynchronous images
>
> Images are downloaded and processed in the background after the product is created.

> [accordion] Variations by SKU
>
> Variations are identified by their SKU. If a variation with that SKU already exists, it is updated instead of creating a new one. By default, existing variations not present in the payload are kept; send `replace_variations: true` to remove them.

> [accordion] Modifiers
>
> If `modifier_groups` is absent in the payload, existing modifiers are preserved. If it is an empty array `[]`, all modifiers are deleted. If it has data, modifiers are completely replaced.

## Validation errors

If the data does not meet the validation rules, the API responds with `422` and details the fields with errors.

```json theme={null}
{
  "message": "The resources field is required.",
  "errors": {
    "resources": ["The resources field is required."]
  }
}
```

> [accordion] Common error messages
>
> | Field | Message |
> | - | - |
> | `resources` | At least one product is required. |
> | `resources` | Cannot process more than 500 products at once. |
> | `resources.*.sku` | Each product must have a SKU. |
> | `resources.*.name` | Each product must have a name. |
> | `resources.*.price` | Each product must have a price. / Price cannot be negative. |
> | `resources.*.stock_type` | Stock type must be either limited or unlimited. |
> | `resources.*.images.*` | Each image must be a valid URL. |
> | `resources.*.variations.*.stock_type` | Variation stock type must be either limited or unlimited. |
> | `resources.*.variations.*.stock` | Variation stock must be an integer. / Cannot be negative. |
> | `resources.*.modifier_groups.*.code` | Each modifier group must have a code. |
> | `resources.*.modifier_groups.*.name` | Each modifier group must have a name. |
> | `resources.*.modifier_groups.*.options` | Each modifier group must have at least one option. |
> | `resources.*.modifier_groups.*.options.*.code` | Each modifier option must have a code. |
> | `resources.*.modifier_groups.*.options.*.name` | Each modifier option must have a name. |
> | `resources.*.tax` | Tax rate must be a number. / cannot be negative. / cannot exceed 100. |
> | `resources.*.replace_variations` | Replace variations flag must be true or false. |
> | `resources.*.features.*.label` | Each feature must have a label. / cannot exceed 255 characters. |
> | `resources.*.features.*.value` | Each feature must have a value. / cannot exceed 200 characters. |

## Limits

* Maximum **500 products** per request in asynchronous mode (default), or **50** in synchronous mode (`X-Sync: true`).
* Maximum **10,000 products** per **60-second** window per store (rate limit). If exceeded, the API responds with `429 Too Many Requests`.
* All products are validated before being processed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.