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

# Products, variants and relations

> Write the full product payload, build configurable products with variants and variant axes, link related products, and retry writes safely.

This guide covers everything you write on a product through the API: its fields, its place in a parent and variant structure, and its links to other products. It is written for integrations that keep WISEPIM in step with an ERP, a storefront or another PIM.

Every path below is relative to `https://wisepim.com/api/public/v1`. Every write in the examples sends an `Idempotency-Key`; see [Retries and idempotency](https://docs.wisepim.com/en/api-reference/introduction.md#retries-and-idempotency) for why.

## Scopes at a glance

| Task | Endpoints | Scopes |
| - | - | - |
| Look up or create attributes | [`GET /attributes`](https://docs.wisepim.com/en/api-reference/attributes/list), [`POST /attributes`](https://docs.wisepim.com/en/api-reference/attributes/create) | `attributes:read`, `attributes:write` |
| Read products and variant axes | [`GET /products`](https://docs.wisepim.com/en/api-reference/products/list), [`GET /products/{id}`](https://docs.wisepim.com/en/api-reference/products/get), [`GET /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/get) | `products:read` |
| Create and update products | [`POST /products`](https://docs.wisepim.com/en/api-reference/products/create), [`PATCH /products/{id}`](https://docs.wisepim.com/en/api-reference/products/update), [`POST /products/batch`](https://docs.wisepim.com/en/api-reference/products/batch) | `products:write` |
| Set or clear variant axes | [`PUT /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/set), [`DELETE /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/clear) | `products:write` |
| Families and axis bindings | [`POST /product-families`](https://docs.wisepim.com/en/api-reference/product-families/create), [`POST /family-attributes`](https://docs.wisepim.com/en/api-reference/family-attributes/create) | `product-families:write`, `family-attributes:write` |
| Read and write relations | [`GET /product-relations`](https://docs.wisepim.com/en/api-reference/product-relations/list), [`POST /product-relations`](https://docs.wisepim.com/en/api-reference/product-relations/create), [`PATCH /product-relations/{id}`](https://docs.wisepim.com/en/api-reference/product-relations/update), [`POST /product-relations/batch`](https://docs.wisepim.com/en/api-reference/product-relations/batch) | `product-relations:read`, `product-relations:write` |
| Delete relations, or batch with `replace: true` | [`DELETE /product-relations/{id}`](https://docs.wisepim.com/en/api-reference/product-relations/delete), [`POST /product-relations/batch`](https://docs.wisepim.com/en/api-reference/product-relations/batch) | `product-relations:delete` (plus `:write` for the batch) |

`products:write` does not include deleting products; that is `products:delete`. The full list is in the [scope catalog](https://docs.wisepim.com/en/api-reference/authentication.md#scopes).

## The product payload

A product read returns one flat JSON object. The tables below group its fields the way you would map them from your own system. All fields except `sku` are optional on a write, and a write changes only the fields you send.

### Identifiers

| Field | Notes |
| - | - |
| `id` | WISEPIM's id. Read-only. |
| `sku` | Your key for the product, unique within the project. Required on create. It cannot be changed afterwards, so `PATCH /products/{id}` rejects it. |
| `ean`, `upc`, `manufacturer_part_number`, `brand`, `supplier` | Plain strings. `upc` is at most 12 characters. |

### Content and localized maps

| Field | Notes |
| - | - |
| `name`, `name_long`, `description`, `short_description` | Content in the project's primary language. |
| `name_localized`, `name_long_localized`, `description_localized`, `short_description_localized` | Maps from locale code to text, for example `{"nl": "Boormachine", "de": "Bohrmaschine"}`. |
| `meta_title`, `meta_description`, `meta_keywords` | SEO metadata in the primary language. |
| `meta_title_localized`, `meta_description_localized`, `meta_keywords_localized` | SEO metadata per locale. |

> [!WARNING]
>
> A localized map is replaced as a whole. Sending `"name_localized": {"de": "Bohrmaschine"}` stores exactly that map, so a Dutch name stored earlier is gone. Read the product first and send the merged map when you only want to change one language.

### Prices and cost

| Field | Notes |
| - | - |
| `price`, `special_price` | Decimal strings with at most two decimals, such as `"89.95"`. At most `99999999.99`. |
| `special_price_start_date`, `special_price_end_date` | ISO-8601 date-times. A time without a timezone is read as UTC. When you send both, the start must not be after the end (`invalid_special_price_window`). |
| `cost` | Your purchase cost, two decimals. |

### Physical data

| Field | Notes |
| - | - |
| `weight` | Decimal string with at most three decimals, such as `"1.650"`. |
| `weight_unit` | One of `g`, `kg`, `oz`, `lb`. Defaults to `kg`. |
| `length`, `width`, `height` | Decimal strings with at most two decimals. |
| `dimension_unit` | One of `mm`, `cm`, `m`, `in`, `ft`. Defaults to `cm`. |

The unit fields describe the numbers you store; WISEPIM does not convert a value when you change its unit.

### Stock

| Field | Notes |
| - | - |
| `manage_stock` | Whether stock is tracked for this product. |
| `stock_quantity` | Integer. |
| `stock_status` | One of `in_stock`, `out_of_stock`, `on_backorder`. |
| `backorders_allowed`, `backorders_notify` | Booleans. |
| `availability_date` | ISO-8601 date-time. |
| `low_stock_threshold` | Integer, 0 or more. |

### Shipping and customs

| Field | Notes |
| - | - |
| `requires_shipping`, `free_shipping`, `is_fragile`, `is_dangerous_good` | Booleans. |
| `shipping_class`, `handling_instructions` | Strings. `handling_instructions` is at most 10,000 characters. |
| `hs_code` | Customs tariff code as a string. |
| `country_of_origin` | Two-letter ISO 3166-1 code. Stored upper-case, so `"de"` is read back as `"DE"`. |

### FAQs

| Field | Notes |
| - | - |
| `faqs` | Ordered list of `{"id", "question", "answer"}` items. Sending it replaces the list. At most 50 items, with a question of at most 300 characters and an answer of at most 5,000 characters. An item with an answer needs a question. Items with neither a question nor an answer are dropped without an error. Answers are sanitized and missing ids are generated. |
| `faqs_localized` | Translations keyed by locale, then by FAQ id. Translations of FAQs that are no longer in the list are dropped. |
| `skip_category_faqs` | Boolean that controls whether the product's category FAQs apply to it. |
| `category_faq_threshold` | Integer from 1 to 50, or `null` for no threshold. Other values are a `422 invalid_faqs`. |

An FAQ write that fails validation is a `422 invalid_faqs`.

### Visibility, status and classification

| Field | Notes |
| - | - |
| `status` | One of `active`, `inactive`, `pending`, `archived`. |
| `is_visible` | Boolean. |
| `category_ids` | Replaces the product's whole category set. Up to 200 ids, all from this project. |
| `attributes` | Attribute values. See [Attribute values](#attribute-values). |
| `product_type`, `parent_id`, `family` | The variant structure. See [Variants](#variants). |

### Read-only fields

`main_image` is owned by the media library and cannot be written here; use the [media endpoints](https://docs.wisepim.com/en/api-reference/media.md). `version`, `created_at` and `updated_at` are maintained by WISEPIM. Sending a field that is not writable is a `422`.

> [!WARNING]
>
> A product read cannot be sent back as a write. `id`, `family`, `main_image`, `version`, `created_at` and `updated_at` are not accepted on a write, and `attributes` is read as a list but written as a map (see [Attribute values](#attribute-values)). Any of these fails request validation with a `422` whose body is `{"error": "Validation error", "detail": [...]}` and has no `code`. Build write bodies from your own fields, not from a GET response.

### Decimals are strings

Prices, cost, weight and dimensions are **decimal strings** on read and accept a string or an integer on write. A JSON float such as `19.99` is rejected, because floats cannot represent every price exactly. It fails request validation before the price is read, so the `422` carries a per-field `detail` array and no `code`. A float with a zero fraction, such as `20.0`, is read as the integer `20` and accepted. Negative numbers, `NaN`, too many decimals and values over the maximum are rejected too.

| You send | Result |
| - | - |
| `"19.99"` | Stored as 19.99 |
| `20` | Stored as 20.00 |
| `19.99` (a float) | `422` validation error with a `detail` array (no `code`) |
| `"1.2345"` as `weight` | `422 invalid_number` (three decimals at most) |

Prices fail with `invalid_price`; `cost`, `weight` and dimensions fail with `invalid_number`. Parse the strings with a decimal type in your own code, not a float.

### Null versus omitted

A field you leave out is not touched. A field you send as `null` is cleared:

* `null` on a price, `cost`, a dimension, a date or an optional text clears it.
* `null` on `name`, `name_long` or `supplier` stores an empty string.
* `null` on a localized map stores an empty map.
* `null` on `parent_id` or `parent_sku` detaches a variant; `null` on `family_id` clears the family.

Booleans, `weight_unit`, `dimension_unit`, `stock_quantity` and `stock_status` have no empty state. Sending `null` for one of them is a `422 invalid_value`; send the value you want instead.

Text that a database cannot store, a NUL character or a lone UTF-16 surrogate, is a `422 invalid_value` in any field, including keys of a map.

### Attribute values

Attribute values are read and written in different shapes. A read returns a list:

```json theme={null}
{
  "attributes": [
    { "code": "voltage", "label": "Voltage", "type": "number", "value": 18, "unit": "V" },
    { "code": "chuck_size", "label": "Chuck size", "type": "number", "value": 13, "unit": "mm" }
  ]
}
```

A write takes a map keyed by attribute code, and only the codes you send change:

```json theme={null}
{
  "attributes": {
    "voltage": { "value": 18, "unit": "V" },
    "chuck_size": 13,
    "colour": null
  }
}
```

* A plain value keeps the unit already stored. `{"value": ..., "unit": "..."}` sets both.
* `null`, or `{"value": null}`, removes the value.
* A list is only valid for a `multiselect` attribute, and an object as the value only for a `range` attribute.
* For `select` and `multiselect` attributes, send the option codes.
* The attribute's own cleaning and validation rules run on every write (`422 invalid_attribute_value`). Units are checked against the attribute's unit set (`422 invalid_unit`).
* `file` and `image` attributes are managed through the [media endpoints](https://docs.wisepim.com/en/api-reference/media.md) and are rejected here.
* An attribute code that does not exist in the project is a `422 unknown_attribute`. Create it first with [`POST /attributes`](https://docs.wisepim.com/en/api-reference/attributes/create).

### A complete create

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/products \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: create-DRL-18V-BL-02" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "DRL-18V-BL-02",
    "ean": "8712345678906",
    "brand": "Torvik",
    "manufacturer_part_number": "TK-DD18-BL",
    "supplier": "Torvik Tools B.V.",
    "name": "Torvik 18V brushless drill driver",
    "name_localized": { "nl": "Torvik 18V koolborstelloze boorschroefmachine" },
    "short_description": "Compact 18V drill driver with a 13 mm keyless chuck.",
    "status": "active",
    "is_visible": true,
    "price": "149.00",
    "special_price": "129.00",
    "special_price_start_date": "2026-12-01T00:00:00Z",
    "special_price_end_date": "2026-12-31T23:59:59Z",
    "cost": "71.40",
    "weight": "1.450",
    "weight_unit": "kg",
    "length": "21.50",
    "width": "7.80",
    "height": "24.00",
    "dimension_unit": "cm",
    "manage_stock": true,
    "stock_quantity": 84,
    "stock_status": "in_stock",
    "low_stock_threshold": 10,
    "hs_code": "84672100",
    "country_of_origin": "DE",
    "is_dangerous_good": false,
    "faqs": [
      { "question": "Is a battery included?", "answer": "No. The drill fits every Torvik 18V battery." }
    ],
    "meta_title": "Torvik 18V brushless drill driver",
    "category_ids": [412],
    "attributes": {
      "voltage": { "value": 18, "unit": "V" },
      "chuck_size": { "value": 13, "unit": "mm" }
    }
  }'
```

The response is `201` with the product as `GET /products/{id}` returns it. A SKU that already exists is a `409 sku_conflict`; use [`POST /products/batch`](https://docs.wisepim.com/en/api-reference/products/batch) when you want create-or-update by SKU.

## Variants

A product with sizes or colours is stored as one **configurable** parent and one product per sellable variant. The parent carries the shared content; each variant carries its own SKU, price, stock and the attribute values that set it apart.

### Structure fields

| Field | Notes |
| - | - |
| `product_type` | One of `simple`, `configurable`, `virtual`, `bundle`, `grouped`. A new product without a type is `simple`. |
| `parent_id` | Makes the product a variant of the configurable product with this id. `null` detaches it. |
| `parent_sku` | Same as `parent_id`, addressed by SKU. In a batch it may name another item of the same batch. Send `parent_id` or `parent_sku`, not both. |
| `family_id` | A product family of this project. `null` clears it. Reads return `family` as `{"id", "code", "name"}`. |
| `family_code` | Write-only alternative to `family_id`, addressed by the family's code. Send one of the two, not both. |

To list a parent's variants, call [`GET /products?parent_id={id}`](https://docs.wisepim.com/en/api-reference/products/list). `GET /products?product_type=configurable` lists the parents.

### Parent rules

WISEPIM applies the same rules as the web editor. They are checked against the state the request leaves behind, so one batch may create a parent together with its variants, or promote a product to configurable and attach variants to it.

* The parent must be a product in this project (`422 unknown_parent`).
* The parent must be `configurable`, must not be a variant itself, and must not be the product itself (`422 invalid_parent`). Variants cannot be nested.
* A variant is never `configurable` (`422 invalid_product_type`).
* A product that has variants must stay `configurable` and cannot become a variant. Detach its variants first (`422 invalid_product_type` or `invalid_parent`).
* WISEPIM does not promote a parent for you. Set `"product_type": "configurable"` on it explicitly, in the same request if you like.

> [!NOTE]
>
> Variants are not product relations. Attach a variant with `parent_id` or `parent_sku`. Use [product relations](#product-relations) for cross-sells, accessories and bundles.

### Variant axes

Variant axes are the attributes that tell a parent's variants apart, such as `size` and `colour`. Exports, imports and the editor read them to group variants. You can set them in three ways.

> [card] Per family
>
> Flag the family's attribute bindings with `is_variant_axis` and give the parent that family. Every configurable product in the family, or in a child family, gets these axes.

> [card] On a product write
>
> Send `variant_axes` on `POST /products`, `PATCH /products/{id}` or a batch item for the parent. The choice is stored on that product.

> [card] Dedicated endpoint
>
> `PUT /products/{id}/variant-axes` stores the choice, `DELETE` removes it, and `GET` shows the axes in effect.

**Per family.** Create a binding with [`POST /family-attributes`](https://docs.wisepim.com/en/api-reference/family-attributes/create) and `"is_variant_axis": true`. Axes from the family and its ancestor families are ordered by the binding's `sort_order` (or the attribute's own sort order when the binding has none), then by attribute code. Nothing needs to be stored on the product.

**Per product.** A product's own choice wins over its family. Send attribute codes in axis order, at most 32:

```bash theme={null}
curl -X PUT https://wisepim.com/api/public/v1/products/52014/variant-axes \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: axes-TEE-ORG-CREW-v1" \
  -H "Content-Type: application/json" \
  -d '{"attribute_codes": ["colour", "size"]}'
```

The `variant_axes` field on a product write does the same as [`PUT /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/set). It runs after the product fields are written, in the same transaction, so it sees variants and values written by the same request. An empty list (`[]`) stores an explicit "this product has no axes".

[`DELETE /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/clear) removes the product's own choice so the family's axes apply again, and returns the axes in effect afterwards.

Only `configurable` products have axes (`422 not_configurable`). Codes must be attributes of this project (`422 unknown_attribute`).

#### Every variant needs a complete, unique combination

When the parent already has variants, setting axes is refused unless each variant has a value for every axis and no two variants share the same combination. The error is `422 invalid_combinations` and lists `incomplete_variant_ids` and `duplicate_variant_ids` (groups of ids that share one combination). Values are compared without regard to case, so `Navy` and `navy` count as the same value.

This means the order of operations matters. Either set the axes before you add variants, or write the variants with their axis values first and the axes after, or do both in one batch as shown in the walkthrough below.

> [!NOTE]
>
> The combination check runs only when axes are set: through `variant_axes` on a product write, or through [`PUT /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/set). Axes that come from the family are not checked when you write a product. If you want WISEPIM to refuse incomplete or duplicate combinations, send `variant_axes` on the parent or call the `PUT` endpoint after writing the variants.

#### Reading the axes and their source

[`GET /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/get) returns the axes in effect, the distinct values per axis, and any problem variants:

```json theme={null}
{
  "product_id": 52014,
  "source": "parent_override",
  "axes": [
    { "attribute_id": 311, "code": "colour", "label": "Colour", "position": 0, "values": ["navy", "white"] },
    { "attribute_id": 310, "code": "size", "label": "Size", "position": 1, "values": ["S", "M", "L"] }
  ],
  "incomplete_variant_ids": [],
  "duplicate_variant_ids": [],
  "warnings": []
}
```

`source` tells you where the axes came from, in order of precedence:

| `source` | Meaning |
| - | - |
| `parent_override` | Stored on this product with `PUT` or `variant_axes`. Wins over everything else. An empty override shows here with no axes. |
| `family` | Bindings flagged `is_variant_axis` on the product's family or an ancestor family. |
| `inferred` | Nothing is configured, so WISEPIM picked the attributes whose values every variant has and that differ between variants. Unique and identifier-like attributes are skipped. |
| `stored_import` | Axis codes recorded by an earlier import. |
| `none` | No axes could be determined. `warnings` then contains `no_axes`. |

If you depend on the axes, set them explicitly. `inferred` can change when variant values change.

## Walkthrough: migrate a product and its items

Many PIMs store a style-level product with sellable items under it: Inriver's Product and Item entities, for example, or a "model" and "SKU" split in an ERP. In WISEPIM the style becomes a configurable parent and each item becomes a variant. This walkthrough moves an organic T-shirt in two colours and three sizes.

**1. Make sure the axis attributes exist**

Look up the attributes your items differ on. You need their ids for the family bindings.

```bash theme={null}
curl "https://wisepim.com/api/public/v1/attributes?codes=colour,size" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

Create any that are missing with [`POST /attributes`](https://docs.wisepim.com/en/api-reference/attributes/create). For `select` attributes, create the options first and send exactly those codes as values (`navy`, `white`, `S`, `M`, `L`). A product write stores the codes you send without checking them against the attribute's options, so a typo is saved as a new value instead of being rejected.

**2. Create the family**

One family per product type in your source PIM is a good start. This needs `product-families:write`.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/product-families \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: family-t-shirts" \
  -H "Content-Type: application/json" \
  -d '{"name": "T-shirts", "code": "t_shirts"}'
```

Note the `id` in the response, here `27`.

**3. Bind the axis attributes to the family**

One binding per axis, with `is_variant_axis` set. `sort_order` sets the axis order. This needs `family-attributes:write`.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/family-attributes \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: family-27-axis-colour" \
  -H "Content-Type: application/json" \
  -d '{"family": 27, "attribute": 311, "is_variant_axis": true, "sort_order": 0}'

curl -X POST https://wisepim.com/api/public/v1/family-attributes \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: family-27-axis-size" \
  -H "Content-Type: application/json" \
  -d '{"family": 27, "attribute": 310, "is_variant_axis": true, "sort_order": 1}'
```

From now on, every configurable product in this family gets `colour` and `size` as axes without anything stored on the product.

**4. Send the parent, its variants and the axes in one batch**

[`POST /products/batch`](https://docs.wisepim.com/en/api-reference/products/batch) is keyed by SKU, and `parent_sku` may point at another item in the same batch in any order. WISEPIM inserts the parents first and the variants after, in one transaction.

`variant_axes` on the parent is optional here because the family already defines the axes. Send it when a product differs from its family, for example a style that only comes in one colour and should vary by `size` alone. It is checked after the variants and their values are written, so the combination rule sees the whole family of items.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/products/batch \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: migrate-TEE-ORG-CREW-2026-11-20" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "sku": "TEE-ORG-CREW",
        "product_type": "configurable",
        "family_code": "t_shirts",
        "variant_axes": ["colour", "size"],
        "name": "Organic cotton crew neck T-shirt",
        "brand": "Northline",
        "description": "Midweight 180 g/m² organic cotton T-shirt with a ribbed crew neck.",
        "status": "active",
        "category_ids": [218]
      },
      { "sku": "TEE-ORG-CREW-NVY-S", "parent_sku": "TEE-ORG-CREW", "family_code": "t_shirts", "name": "Organic cotton crew neck T-shirt, navy, S", "price": "29.95", "stock_quantity": 40, "ean": "8719876543210", "attributes": { "colour": "navy", "size": "S" } },
      { "sku": "TEE-ORG-CREW-NVY-M", "parent_sku": "TEE-ORG-CREW", "family_code": "t_shirts", "name": "Organic cotton crew neck T-shirt, navy, M", "price": "29.95", "stock_quantity": 65, "ean": "8719876543227", "attributes": { "colour": "navy", "size": "M" } },
      { "sku": "TEE-ORG-CREW-NVY-L", "parent_sku": "TEE-ORG-CREW", "family_code": "t_shirts", "name": "Organic cotton crew neck T-shirt, navy, L", "price": "29.95", "stock_quantity": 38, "ean": "8719876543234", "attributes": { "colour": "navy", "size": "L" } },
      { "sku": "TEE-ORG-CREW-WHT-S", "parent_sku": "TEE-ORG-CREW", "family_code": "t_shirts", "name": "Organic cotton crew neck T-shirt, white, S", "price": "29.95", "stock_quantity": 22, "ean": "8719876543241", "attributes": { "colour": "white", "size": "S" } },
      { "sku": "TEE-ORG-CREW-WHT-M", "parent_sku": "TEE-ORG-CREW", "family_code": "t_shirts", "name": "Organic cotton crew neck T-shirt, white, M", "price": "29.95", "stock_quantity": 51, "ean": "8719876543258", "attributes": { "colour": "white", "size": "M" } },
      { "sku": "TEE-ORG-CREW-WHT-L", "parent_sku": "TEE-ORG-CREW", "family_code": "t_shirts", "name": "Organic cotton crew neck T-shirt, white, L", "price": "29.95", "stock_quantity": 17, "ean": "8719876543265", "attributes": { "colour": "white", "size": "L" } }
    ]
  }'
```

The response lists every item with its new `id` and whether it was `created` or `updated`:

```json theme={null}
{
  "results": [
    { "index": 0, "sku": "TEE-ORG-CREW", "id": 52014, "action": "created" },
    { "index": 1, "sku": "TEE-ORG-CREW-NVY-S", "id": 52015, "action": "created" }
  ],
  "summary": { "created": 7, "updated": 0 }
}
```

If any item is invalid, including a variant with a missing or duplicate axis combination, the whole batch is rejected with `422 batch_invalid` and nothing is written.

The axes are checked only after every other item passes validation, so fixing a first round of errors can reveal an `invalid_combinations` error on the next attempt. In a batch that entry has only `index`, `sku`, `code` and `message`, without the variant id lists. To find the problem variants, write the variants without `variant_axes` and read [`GET /products/{id}/variant-axes`](https://docs.wisepim.com/en/api-reference/variant-axes/get).

**5. Read the axes back**

Confirm the structure before you move on to the next style.

```bash theme={null}
curl https://wisepim.com/api/public/v1/products/52014/variant-axes \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

Check that `axes` lists `colour` and `size`, and that `incomplete_variant_ids` and `duplicate_variant_ids` are empty. `source` is `parent_override` because the batch sent `variant_axes`; without it, it would be `family`.

The same batch in code, with one idempotency key per logical batch:

```python Python theme={null}
import os
import requests

BASE = "https://wisepim.com/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WISEPIM_API_KEY']}"}


def migrate_style(style, items, run_id):
    payload = {"items": [
        {
            "sku": style["sku"],
            "product_type": "configurable",
            "family_code": style["family_code"],
            "variant_axes": style["axes"],
            "name": style["name"],
        },
        *[
            {
                "sku": item["sku"],
                "parent_sku": style["sku"],
                "family_code": style["family_code"],
                "price": item["price"],  # keep prices as strings, e.g. "29.95"
                "attributes": item["axis_values"],
            }
            for item in items
        ],
    ]}
    response = requests.post(
        f"{BASE}/products/batch",
        json=payload,
        headers={**HEADERS, "Idempotency-Key": f"migrate-{style['sku']}-{run_id}"},
        timeout=60,
    )
    if response.status_code == 422 and response.json().get("code") == "batch_invalid":
        for error in response.json()["errors"]:
            print(error["index"], error["sku"], error["code"], error["message"])
    response.raise_for_status()
    return response.json()["results"]
```

```javascript Node.js theme={null}
const BASE = "https://wisepim.com/api/public/v1";

async function migrateStyle(style, items, runId) {
  const payload = {
    items: [
      {
        sku: style.sku,
        product_type: "configurable",
        family_code: style.familyCode,
        variant_axes: style.axes,
        name: style.name,
      },
      ...items.map((item) => ({
        sku: item.sku,
        parent_sku: style.sku,
        family_code: style.familyCode,
        price: item.price, // keep prices as strings, e.g. "29.95"
        attributes: item.axisValues,
      })),
    ],
  };
  const response = await fetch(`${BASE}/products/batch`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WISEPIM_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `migrate-${style.sku}-${runId}`,
    },
    body: JSON.stringify(payload),
  });
  const body = await response.json();
  if (response.status === 422 && body.code === "batch_invalid") {
    for (const error of body.errors) {
      console.error(error.index, error.sku, error.code, error.message);
    }
  }
  if (!response.ok) throw new Error(`${response.status} ${body.code ?? body.error}`);
  return body.results;
}
```

> [!TIP]
>
> A batch holds at most 200 items. Group items by style so a parent and all its variants always travel in the same batch. A style with more than 199 variants needs the parent in an earlier batch and its variants spread over later ones, each addressing the parent by `parent_sku`.

## Product relations

Relations link one product to another for merchandising: cross-sells, accessories, replacement parts and bundle contents. A relation points one way. If the drill should list the battery and the battery should list the drill, create two relations.

| `relation_type` | Typical use |
| - | - |
| `cross_sell` | "Customers also bought" |
| `up_sell` | A better or larger alternative |
| `related` | Generally related products |
| `replacement` | The successor of a discontinued product |
| `accessory` | Batteries, bits, cases |
| `bundle_item` | A component of a bundle, with `quantity` and `is_required` |
| `grouped_item` | A member of a grouped product |

Each relation has a `position` (order within the product's relations of that type), a `quantity` (default 1) and `is_required` (default `true`). The products and the type identify a relation and cannot be changed; to change them, delete the relation and create a new one. [`PATCH /product-relations/{id}`](https://docs.wisepim.com/en/api-reference/product-relations/update) changes `position`, `quantity` and `is_required`.

### By id or by SKU

On create you can address either product by id (`product`, `related_product`) or by SKU (`product_sku`, `related_product_sku`). Send exactly one of each pair.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/product-relations \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: rel-DRL-18V-BL-02-accessory-BAT-18V-4AH" \
  -H "Content-Type: application/json" \
  -d '{"product_sku": "DRL-18V-BL-02", "related_product_sku": "BAT-18V-4AH", "relation_type": "accessory"}'
```

Reads always return ids. [`GET /product-relations?product_id=...`](https://docs.wisepim.com/en/api-reference/product-relations/list) lists a product's relations; `related_product_id` and `relation_type` filter further. The same pair and type twice is a `409 relation_conflict`, and a product cannot be related to itself (`422 invalid_relation`).

### Batch upsert, with or without replace

[`POST /product-relations/batch`](https://docs.wisepim.com/en/api-reference/product-relations/batch) upserts up to 200 relations at once, keyed by product, related product and type. It is validated first and applied atomically: any invalid item returns `422 batch_invalid` with one entry per item and nothing is written. Each result is `created`, `updated` or `unchanged`, and `summary` counts each action plus `deleted`.

With `"replace": true`, every (product, relation type) pair named in the batch ends with exactly the relations you listed. The other relations of that type on that product are deleted. Relation types and products you did not mention are left alone. This is the right mode for a sync from a source that always sends the complete list, and it needs `product-relations:delete` as well as `:write`.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/product-relations/batch \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: rel-sync-DRL-18V-BL-02-2026-11-20" \
  -H "Content-Type: application/json" \
  -d '{
    "replace": true,
    "items": [
      { "product_sku": "DRL-18V-BL-02", "related_product_sku": "BAT-18V-4AH", "relation_type": "accessory" },
      { "product_sku": "DRL-18V-BL-02", "related_product_sku": "CHG-18V-FAST", "relation_type": "accessory" },
      { "product_sku": "DRL-18V-BL-02", "related_product_sku": "BIT-SET-32", "relation_type": "accessory" }
    ]
  }'
```

### Positions

* Without `position`, a new relation goes one after the highest position that remains for that product and type. Gaps left by deleted relations are not filled.
* A relation that already exists keeps its position unless you send `position`, also with `replace: true`.
* With `replace: true`, relations that are new to the list are numbered in the order sent, after the highest position that remains. Sending the same relations in a new order does not reorder them.
* To mirror the order of your source system, send an explicit `position` on every item.

Every relation write bumps the owning product's `version` and `updated_at`, so an incremental sync on `updated_since` picks up relation changes.

## Concurrency and retries

### `version` and `updated_at`

Every product has a `version` that increases on each change, together with `updated_at`. A write that changes nothing does not bump them. Changes to categories, attribute values and relations bump them too. Use them to detect that a product changed since you last read it.

The API does not take a version precondition: a write is applied to the current state, and the last write wins. If two systems edit the same fields, decide which one owns each field rather than relying on ordering.

### `write_conflict`

Product writes lock the rows they touch. When the catalog changes underneath a write anyway, for example a category, attribute or family it refers to is deleted mid-request, or another writer conflicts with it, the write returns `409 write_conflict` and **nothing is written**. Retry the same request unchanged, with the same `Idempotency-Key`.

### `Idempotency-Key`

Send an `Idempotency-Key` on every write and reuse it for every retry of that write. A retry with the same key and the same request returns the original status and body and applies nothing again. The same key with a different request is a `409 idempotency_conflict`. A failed write stores no record, so retrying a `409 write_conflict` or a `5xx` with the same key runs it again normally. Keys are remembered for 30 days.

[`POST /products/batch`](https://docs.wisepim.com/en/api-reference/products/batch) is keyed by SKU, so retrying it without a header does not create duplicates. The header still matters: it returns the original `created` and `updated` results instead of reporting every item as `updated` on the second run.

### Batch atomicity

A product batch is all or nothing. Every item is validated first: schema, duplicate SKUs within the batch (`duplicate_sku`), unknown categories, attributes and families, invalid values, parent rules, field permissions, variant axes and the plan's product limit. If anything fails, the response is `422 batch_invalid` with an `errors` list of `{index, sku, code, message}` and no item is written. Fix the listed items and resend the whole batch.

```json theme={null}
{
  "error": "Batch rejected: 1 invalid item(s); nothing was written",
  "code": "batch_invalid",
  "request_id": "7c1e04aa",
  "errors": [
    { "index": 3, "sku": "TEE-ORG-CREW-NVY-L", "code": "invalid_price", "message": "price must be a decimal string such as \"19.99\"" }
  ]
}
```

## Field permissions for custom roles

An API key acts with the authority of the team member who created it. When that member has a custom role that limits which fields or attributes they may edit, the API applies the same limits. A write that touches a field outside the role is refused, never silently dropped, so a `2xx` always means every value you sent was stored.

On `POST /products` and `PATCH /products/{id}` the response is `403 field_permission_denied`:

```json theme={null}
{
  "error": "The member who issued this key may not edit these fields",
  "code": "field_permission_denied",
  "request_id": "a41d9e07",
  "denied_fields": ["price", "cost"],
  "denied_attributes": ["voltage"]
}
```

In a batch, each affected item appears in `batch_invalid` with the code `field_permission_denied` and nothing is written. `variant_axes` and the parent fields are permission-checked fields too, including on the `PUT` and `DELETE` variant-axes endpoints. Owners and built-in roles have no field-level limits. To fix it, either remove the fields from the request or have the key reissued by a member whose role allows them.

## Common errors

| Status and code | Cause | What to do |
| - | - | - |
| `409 sku_conflict` | `POST /products` with a SKU that already exists | Use `PATCH /products/{id}`, or `POST /products/batch` to create or update by SKU |
| `409 write_conflict` | The catalog changed while the write ran | Retry unchanged with the same `Idempotency-Key`; nothing was written |
| `409 idempotency_conflict` | Same key reused for a different request | Use a new key for each distinct write |
| `409 relation_conflict` | The relation already exists | Update it, or use the relations batch to upsert |
| `403 field_permission_denied` | The key's issuer has a custom role without these fields | Drop the fields listed in `denied_fields` and `denied_attributes`, or reissue the key |
| `403 product_limit_exceeded` | The plan has no room for more products. In `POST /products/batch` it is reported inside `422 batch_invalid` on the first item that does not fit. | Upgrade the plan or remove products |
| `422` with `detail` and no `code` | The body failed request validation: a JSON float for a decimal, a read-only field such as `id` or `version`, an unknown field, or a wrong type | Read the field paths in `detail` and fix the body |
| `422 batch_invalid` | At least one batch item is invalid | Fix each entry in `errors` and resend the whole batch |
| `422 duplicate_sku` | The same SKU appears twice in one batch (reported inside `batch_invalid`) | Send each SKU once per batch |
| `422 invalid_sku` | A blank SKU, or a batch create without a SKU | Send a non-empty SKU |
| `422 invalid_price`, `invalid_number` | Negative, `NaN`, too many decimals or too large | Send a decimal string such as `"29.95"` |
| `422 invalid_status` | `status` is `null` or not one of `active`, `inactive`, `pending`, `archived` | Send one of the four values |
| `422 invalid_value` | A bad `weight_unit`, `dimension_unit`, `stock_status` or `country_of_origin`, `null` on a field with no empty state, or unstorable text | Send a real value from the allowed list |
| `422 unknown_category`, `unknown_attribute` | An id or code that does not exist in this project | Create the category or attribute first |
| `422 invalid_attribute_value`, `invalid_unit` | Value has the wrong shape for the attribute's type or fails its validation rules; unit not in its unit set | Check the attribute's configuration with [`GET /attributes/{id}/configuration`](https://docs.wisepim.com/en/api-reference/attributes/configuration) |
| `422 unknown_family`, `ambiguous_family`, `invalid_family` | No family with that id or code, several families share the code, or both `family_id` and `family_code` were sent | Send one of the two; use `family_id` when codes are not unique |
| `422 unknown_parent`, `invalid_parent` | Parent missing, not configurable, itself a variant, or the product itself | Create the parent as `configurable` first, or in the same batch |
| `422 invalid_product_type` | Unknown or `null` type, a configurable variant, or demoting a parent that has variants | Detach variants before changing the parent's type |
| `422 not_configurable` | Variant axes on a product that is not `configurable` | Set `product_type` to `configurable` |
| `422 invalid_combinations` | A variant lacks an axis value, or two variants share a combination | Fix the variants in `incomplete_variant_ids` and `duplicate_variant_ids` (in a batch, read them with `GET /products/{id}/variant-axes`), then set the axes |
| `422 invalid_axes` | The axes sent to the variant-axes endpoints or in `variant_axes` cannot be stored on this product, for example because it has too many variants to check in one request | Read `error`; it names the reason |
| `422 invalid_faqs` | Over 50 items, a question over 300 or an answer over 5,000 characters, an answer without a question, or a threshold outside 1 to 50 | Keep to the limits; read `field` and `error` |
| `422 invalid_relation_type` | A relation type that does not exist, on relation create, list or batch | Use one of the relation types listed on the [relations reference](https://docs.wisepim.com/en/api-reference/product-relations/create.md) |
| `422 invalid_special_price_window` | Special price start after its end | Correct the dates |
| `422 invalid_reference`, `invalid_relation`, `duplicate_relation` | A relation names a missing product or both id and SKU, relates a product to itself, or repeats in one batch | Send exactly one of id and SKU per product, and each relation once |
| `413 payload_too_large` | Request body over 10 MiB | Split the batch |

## Related

> [card] [Batch upsert products](https://docs.wisepim.com/en/api-reference/products/batch.md)
>
> Create or update up to 200 products by SKU in one atomic call.

> [card] [Variant axes](https://docs.wisepim.com/en/api-reference/variant-axes/get.md)
>
> Read, set and clear the axes of a configurable product.

> [card] [Media](https://docs.wisepim.com/en/api-reference/media.md)
>
> Upload images and files, attach them to products and set the main image.

> [card] [Catalog entities](https://docs.wisepim.com/en/api-reference/catalog.md)
>
> Families, attributes, categories and the other resources a product refers to.


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