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 exceptsku are optional on a write, and a write changes only the fields you send.
Identifiers
Content and localized maps
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.
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 as19.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 asnull is cleared:
nullon a price,cost, a dimension, a date or an optional text clears it.nullonname,name_longorsupplierstores an empty string.nullon a localized map stores an empty map.nullonparent_idorparent_skudetaches a variant;nullonfamily_idclears the family.
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 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
multiselectattribute, and an object as the value only for arangeattribute. - For
selectandmultiselectattributes, 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). fileandimageattributes 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 withPOST /attributes.
A complete create
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
configurableand cannot become a variant. Detach its variants first (422 invalid_product_typeorinvalid_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 assize 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.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:
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 is422 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 Note the
product-families:write.id in the response, here 27.3
Bind the axis attributes to the family
One binding per axis, with From now on, every configurable product in this family gets
is_variant_axis set. sort_order sets the axis order. This needs family-attributes:write.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.id and whether it was created or updated: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.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.
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 withreplace: 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
positionon every item.
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 a2xx always means every value you sent was stored.
On POST /products and PATCH /products/{id} the response is 403 field_permission_denied:
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
Related
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.

