Skip to main content
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 for why.

Scopes at a glance

products:write does not include deleting products; that is products:delete. The full list is in the scope catalog.

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

Content and localized maps

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

Physical data

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

Stock

Shipping and customs

FAQs

An FAQ write that fails validation is a 422 invalid_faqs.

Visibility, status and classification

Read-only fields

main_image is owned by the media library and cannot be written here; use the media endpoints. version, created_at and updated_at are maintained by WISEPIM. Sending a field that is not writable is a 422.
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). 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. 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:
A write takes a map keyed by attribute code, and only the codes you send change:
  • 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 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.

A complete create

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 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

To list a parent’s variants, call GET /products?parent_id={id}. 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.
Variants are not product relations. Attach a variant with parent_id or parent_sku. Use 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.

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.

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.

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 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:
The variant_axes field on a product write does the same as PUT /products/{id}/variant-axes. 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 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.
The combination check runs only when axes are set: through variant_axes on a product write, or through PUT /products/{id}/variant-axes. 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 returns the axes in effect, the distinct values per axis, and any problem variants:
source tells you where the axes came from, in order of precedence: 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.
Create any that are missing with POST /attributes. 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.
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.
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 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.
The response lists every item with its new id and whether it was created or updated:
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.
5

Read the axes back

Confirm the structure before you move on to the next style.
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:
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. 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} 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.
Reads always return ids. GET /product-relations?product_id=... 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 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.

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 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.

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:
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

Batch upsert products

Create or update up to 200 products by SKU in one atomic call.

Variant axes

Read, set and clear the axes of a configurable product.

Media

Upload images and files, attach them to products and set the main image.

Catalog entities

Families, attributes, categories and the other resources a product refers to.