API docs by Redocly

NetSeller Commerce API (1.0.0)

Download OpenAPI specification:

Public, versioned HTTP API for NetSeller commerce integrations. All responses use a shared envelope with data, meta, and errors. API base URLs belong to individual NetSeller installations; this documentation host does not proxy or execute Commerce API requests.

Commerce API developer guide

System

API availability and operational status

Get API status

Confirms that the versioned API surface is available.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Catalog

Catalog reads and controlled writes

List products

Returns products assigned to the resolved shop. The collection defaults to active products; use active=false or active=all to include other states. q performs a case-insensitive substring search across the effective name, short name, SKU/article number, EAN, manufacturer number, and short description. The long description is not searched. Product text is resolved for the requested language with the shop default language and product master data as fallbacks. Product prices are resolved for quantity one using the selected currency and optional price list. Resolved quantity tiers and a reservation-adjusted availability summary for the shop's default inventory location are included with each product.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

sort
string^-?(id|name|sku|updatedAt)(,-?(id|name|sku|up...
Default: "id"
Example: sort=-updatedAt,name

Comma-separated product fields. Supported fields are id, name, sku, and updatedAt. Prefix a field with - for descending order.

q
string <= 200 characters
Examples:
  • q=iPhone -

Case-insensitive substring search across the effective localized name, short name, SKU/article number, EAN, manufacturer number, and short description. The long description is not searched.

active
string
Default: "true"
Enum: "true" "false" "all"
Examples:
  • active=all -

Filters by product active state. true returns active products, false returns inactive products, and all returns both states.

categoryId
Array of integers non-empty unique [ items >= 1 ]
Examples:
  • categoryId=12,18 -

Comma-separated positive category IDs. A product matches when it is assigned to at least one listed category in the resolved shop.

manufacturerId
Array of integers non-empty unique [ items >= 1 ]
Examples:
  • manufacturerId=3,7 -

Comma-separated positive manufacturer IDs. A product matches when its manufacturer is included in the list.

updatedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedAfter=2026-07-01T00:00:00Z

Exclusive lower boundary for updatedAt. Only products with updatedAt > updatedAfter are returned.

updatedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedBefore=2026-08-01T00:00:00Z

Exclusive upper boundary for updatedAt. Only products with updatedAt < updatedBefore are returned. When both boundaries are present, this value must be later than updatedAfter.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a product

Creates one shared product master record, assigns it only to the resolved shop, stores its localized text in the resolved language, and creates its canonical base price in the resolved currency. New products default to inactive unless active: true is supplied.

A supplied compareAtAmount must be greater than amount; it becomes the canonical base price while amount becomes the effective canonical sale price. Without it, amount is the canonical base price. Products without quantity pricing still store one canonical threshold at minQuantity: 1; the required price object creates it automatically.

Product SKUs are global identifiers. An existing SKU returns 409 product_sku_conflict. Price lists, media, additional shop assignments, shop overrides, category assignments, variants, and inventory are not created implicitly. priceListId is not supported.

A canonical slug is generated from name. An optional seo object may set a manual slug and localized metadata for the resolved language.

Authentication with the catalog:write scope and Commerce request context is required.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
sku
required
string [ 1 .. 120 ] characters
ean
string or null^(?:[0-9]{8}|[0-9]{12,14})$
name
required
string [ 1 .. 255 ] characters

Product name in the resolved request language.

shortName
string or null <= 50 characters
description
string or null
shortDescription
string or null

May contain markup; rendered text is limited to 255 characters.

manufacturerNumber
string or null <= 120 characters
manufacturerId
integer or null >= 1

Optional manufacturer assigned to the resolved shop.

taxRateId
required
integer >= 1
deliveryTimeId
integer or null >= 1
minimumOrderQuantity
integer >= 1
Default: 1
active
boolean
Default: false
fulfillmentMode
string
Default: "shipping_and_pickup"
Enum: "shipping_and_pickup" "pickup_only"
object (ProductMeasurementWrite) non-empty

Product measurements. Omitted properties remain unchanged. A null decimal value clears that measurement; null or zero for measurementUnitId clears the assigned active measurement unit.

object (ConnectorCustomFieldWriteValues) <= 100 properties

Complete replacement of all active connector-visible custom-field values for the entity in the resolved shop. Keys are technical custom- field keys. Null clears a scalar value; an empty array clears a multi-select value. Definitions not visible to connectors cannot be addressed and remain unchanged.

object (CatalogSeoWrite) non-empty

SEO changes for the resolved language. A non-empty slug creates a normalized manual canonical slug. slug: null resets the canonical to automatic generation from the localized name. Changing a canonical preserves its former value as a 301 history entry. Metadata properties are partial; null or an empty string clears the supplied property.

required
object (ProductCreatePrice)

Canonical quantity-one price. Product creation stores this as the required minQuantity: 1 entry even when no quantity pricing is used.

Responses

Request samples

Content type
application/json
{
  • "sku": "ERP-501",
  • "ean": "7612345678901",
  • "name": "API product",
  • "shortDescription": "Created by the ERP connector",
  • "manufacturerId": 5,
  • "taxRateId": 2,
  • "deliveryTimeId": 3,
  • "minimumOrderQuantity": 1,
  • "active": false,
  • "fulfillmentMode": "shipping_and_pickup",
  • "seo": {
    },
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a product

Returns one product when it is assigned to the resolved shop, independently of its active state. The active response field exposes that state. The detail includes its resolved product price and quantity tiers, category assignments, active variants with their own resolved prices and quantity tiers, localized option values and availability, active catalog images, resolved SEO metadata, and connector-visible product custom fields. Embedded variants remain compact and expose their custom fields through the variant detail endpoint. Unassigned products are not exposed.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update product base data

Partially updates one shared product assigned to the resolved shop. Omitted fields remain unchanged. Localized text affects only the resolved language and canonical pricing only the resolved currency.

price updates the quantity-one canonical tier. priceTiers replaces all canonical tiers in the resolved currency; its first positive minQuantity threshold may be greater than one. The two fields cannot be combined. Use an empty string to clear optional text and 0 to clear manufacturerId or deliveryTimeId.

A product without quantity pricing must retain one canonical entry at minQuantity: 1; use price or a one-element priceTiers array for that case. A higher first threshold intentionally leaves lower quantities without a canonical price.

Renaming synchronizes an automatic canonical slug but never overwrites a manual slug. seo.slug sets a manual canonical slug; null resets it to automatic generation. Previous canonicals remain 301 history.

Shop assignments are preserved and cannot be changed here. Use active: false for reversible deactivation; the public API exposes no destructive product DELETE because products can retain operational and cross-shop references. Authentication with the catalog:write scope is required.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
non-empty
sku
string [ 1 .. 120 ] characters
ean
string^(?:|[0-9]{8}|[0-9]{12,14})$
name
string [ 1 .. 255 ] characters

Product name in the resolved request language.

shortName
string <= 50 characters
description
string
shortDescription
string

May contain markup; rendered text is limited to 255 characters.

manufacturerNumber
string <= 120 characters
manufacturerId
integer >= 0

Manufacturer assigned to the resolved shop; zero clears it.

taxRateId
integer >= 1
deliveryTimeId
integer >= 0

Delivery time ID; zero clears it.

minimumOrderQuantity
integer >= 1
active
boolean
fulfillmentMode
string
Enum: "shipping_and_pickup" "pickup_only"
object (ProductMeasurementWrite) non-empty

Product measurements. Omitted properties remain unchanged. A null decimal value clears that measurement; null or zero for measurementUnitId clears the assigned active measurement unit.

object (ConnectorCustomFieldWriteValues) <= 100 properties

Complete replacement of all active connector-visible custom-field values for the entity in the resolved shop. Keys are technical custom- field keys. Null clears a scalar value; an empty array clears a multi-select value. Definitions not visible to connectors cannot be addressed and remain unchanged.

object (CatalogSeoWrite) non-empty

SEO changes for the resolved language. A non-empty slug creates a normalized manual canonical slug. slug: null resets the canonical to automatic generation from the localized name. Changing a canonical preserves its former value as a 301 history entry. Metadata properties are partial; null or an empty string clears the supplied property.

object (ProductCreatePrice)

Canonical quantity-one price. Product creation stores this as the required minQuantity: 1 entry even when no quantity pricing is used.

Array of objects (ProductUpdatePriceTier) [ 1 .. 100 ] items

Complete replacement for canonical tiers in the resolved currency. Quantities must be unique and positive; the first threshold may be greater than one. Every tier must use one shared amountType. A product without quantity pricing uses one entry at minQuantity 1.

Responses

Request samples

Content type
application/json
{
  • "name": "Updated API product",
  • "deliveryTimeId": 0,
  • "active": true,
  • "seo": {
    },
  • "priceTiers": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get resolved product prices

Returns the current resolved price and effective quantity tiers for one product assigned to the resolved shop, regardless of its active state. Resolution applies the selected shop's base-price override, the optional global price-list override, and applicable marketing price actions. Missing price-list rows fall back to the resolved base price.

This compact response represents the main product only. It does not expose variant prices, raw price records, or price-list override rows.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List raw product price-list rows

Returns stored product price-list rows without resolving base-price fallback, shop overrides, inheritance, or marketing price actions. The selected shop authorizes product visibility only; rows are global. Omit currency and priceListId to return all stored rows.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$

Optional ISO currency filter; omit it to include every currency.

priceListId
integer >= 1

Optional global price-list filter; omit it to include every price list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a product price-list row

Creates one global product price-list override row in the resolved currency. Price list, currency, and minimum quantity must be unique.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
priceListId
required
integer >= 1
minQuantity
integer >= 1
Default: 1
amount
required
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "priceListId": 1,
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a product price-list row

Updates mutable values while preserving row identity, price list, and currency.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
non-empty
minQuantity
integer >= 1
amount
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a product price-list row

Deletes the selected raw product price-list row without changing canonical prices or other quantity tiers.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Add an image to a product

Adds one active image to the gallery of a product assigned to the resolved shop. Send JSON with mediaAssetId to reuse an existing media-library image, or send one file as multipart/form-data to upload and assign a new image in one request.

Existing product images, downloads, and other media roles are preserved. Without sortOrder, a new image is appended after the current product images. Repeating an existing assignment is idempotent and returns 200; a newly created assignment returns 201. The response is the authoritative public product detail.

Supported uploads are JPG, PNG, GIF, WebP, AVIF, and SVG. The configured media upload-size limit applies. Product downloads and external videos are outside this image-specific contract.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema:
required
mediaAssetId
required
integer >= 1

Existing active image asset to assign to the product.

sortOrder
integer [ 0 .. 2147483647 ]

Optional gallery order; lower values are returned first.

Responses

Request samples

Content type
{
  • "mediaAssetId": 91,
  • "sortOrder": 20
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace and order a product image gallery

Replaces the complete product image gallery with the ordered mediaAssetIds array. Every ID must reference a distinct active image; the first becomes the primary image. An empty array clears the gallery and an unchanged retry avoids rewriting usages.

Product downloads and every non-gallery media role are preserved. Downloads and external media require separate future contracts because they have different metadata, delivery, and lifecycle semantics.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
mediaAssetIds
required
Array of integers <= 100 items unique [ items [ 1 .. 2147483647 ] ]

Complete ordered set of active images assigned to the product.

Responses

Request samples

Content type
application/json
{
  • "mediaAssetIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Remove one image from a product gallery

Removes only the selected product image assignment. The media-library asset, product downloads, external media, and all other usages remain unchanged. The authoritative product detail is returned.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

mediaAssetId
required
integer >= 1
Example: 91

Positive media-asset identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Add shop assignments to a product

Adds one or more active shops to a shared product without removing existing assignments. The product must already be assigned to the resolved shopId context. Every target shop must also be assigned to the authenticated API client.

Duplicate target IDs are collapsed. A request that creates at least one assignment returns 201; an identical retry is idempotent and returns 200. Both responses contain the authoritative complete shop assignment set visible to the API client; assignments outside its shop access are not exposed.

Pickup-only products require an active pickup shipping method in every requested shop. Base data, translations, prices, and shop-specific overrides are not copied or replaced. Existing category assignments are projected to the newly assigned shops by the product domain service.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
shopIds
required
Array of integers non-empty [ items [ 1 .. 2147483647 ] ]

Active target shops assigned to the authenticated API client.

Responses

Request samples

Content type
application/json
{
  • "shopIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace the accessible shop assignments of a product

Replaces the product assignments within the authenticated API client's active shop-access boundary. Assignments to shops outside that boundary are preserved and never exposed. This makes the submitted shopIds authoritative for every shop the client is allowed to manage while preventing accidental removal of hidden assignments.

The product must be available in the resolved shopId, and that shop must remain in the submitted set so the mutation cannot invalidate its own context. Every submitted shop must be active and assigned to the API client. Omitting another accessible shop removes that assignment. An identical retry is idempotent and returns 200.

Pickup-only products require an active pickup shipping method in every submitted shop. Existing category assignments are reprojected by the product domain service. Base data, translations, prices, and overrides are not copied or replaced.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
shopIds
required
Array of integers non-empty [ items [ 1 .. 2147483647 ] ]

Active target shops assigned to the authenticated API client.

Responses

Request samples

Content type
application/json
{
  • "shopIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace product category assignments

Replaces the complete global category-assignment set for a product available in the resolved shop. Every submitted category must also be available in that shop. Unknown and shop-foreign category IDs use the same validation response and are not disclosed.

Nested selections automatically include their available ancestors, matching Admin catalog authoring. An empty categoryIds array removes every assignment. Repeating an unchanged request is idempotent.

The shared assignment set is projected only into shops where both the product and category are assigned. The response is the authoritative product detail resolved for the current Commerce API context.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
categoryIds
required
Array of integers <= 100 items unique [ items [ 1 .. 2147483647 ] ]

Complete desired global category-assignment set. Empty removes all assignments. Assigned ancestors are added automatically.

Responses

Request samples

Content type
application/json
{
  • "categoryIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace product marking assignments

Replaces the complete ordered product-marking assignment set in the resolved shop. Only active global marking definitions may be assigned; unknown and inactive IDs use the same validation response.

Array order defines display order. An empty array removes every assignment in the selected shop. Optional activation bounds must be RFC 3339 UTC values and are supported only by marking definitions configured for date ranges. Repeating an unchanged request is idempotent and avoids a rewrite.

The response is authoritative product detail for the current Commerce API context. Its markings collection includes only assignments active at response time, so future scheduled assignments may not yet appear.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
required
Array of objects (ProductMarkingAssignmentWrite) <= 100 items

Complete desired assignment set for the resolved shop. Array order defines display order; empty removes every assignment.

Responses

Request samples

Content type
application/json
{
  • "assignments": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace a product specification set and typed values

Atomically replaces the product's specification-set assignment and complete typed value collection. The set, submitted definitions, active set items, and option IDs are validated without disclosing unavailable registry entries. Required set items must have values.

Every value object has exactly one field matching its definition's value type. Text targets the resolved request language while preserving other stored translations. Array omission removes optional values. Set specificationSetId to 0 with an empty values array to clear the complete state. Identical retries avoid rewriting stored rows.

Product detail exposes only active, storefront-visible, present values, so stored administrative-only definitions may be absent from the response.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
specificationSetId
required
integer [ 0 .. 2147483647 ]

Active set ID, or zero to remove the complete specification state.

required
Array of ProductSpecificationTextWrite (object) or ProductSpecificationNumberWrite (object) or ProductSpecificationDecimalWrite (object) or ProductSpecificationBooleanWrite (object) or ProductSpecificationDateWrite (object) or ProductSpecificationSingleOptionWrite (object) or ProductSpecificationMultiOptionWrite (object) <= 250 items

Complete typed value collection for the selected set.

Responses

Request samples

Content type
application/json
{
  • "specificationSetId": 9,
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get ordered product accessory groups

Returns the global ordered accessory-group assignments for a product available in the resolved shop. Group names use the requested language and configured fallback language. Internal assignment IDs and global group product counts are not exposed.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace ordered product accessory groups

Replaces the complete global ordered accessory-group assignment set. Array order defines display order, an empty array clears the set, and unchanged retries produce the same authoritative result. Every ID must identify an existing global accessory group.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
accessoryGroupIds
required
Array of integers <= 100 items unique [ items [ 1 .. 2147483647 ] ]

Complete ordered global accessory-group assignment set.

Responses

Request samples

Content type
application/json
{
  • "accessoryGroupIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get ordered direct accessory products

Returns direct accessory products assigned to the source product and available in the resolved shop. Foreign-shop assignments remain hidden.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace ordered direct accessory products

Replaces the ordered direct-accessory set visible in the resolved shop. Array order defines display order and an empty array clears the visible set. Existing assignments to products outside the API client's current shop boundary are preserved and remain undisclosed. Self-relations and unavailable product IDs are rejected with the same validation response.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
productIds
required
Array of integers <= 100 items unique [ items [ 1 .. 2147483647 ] ]

Complete ordered visible direct-accessory product set.

Responses

Request samples

Content type
application/json
{
  • "productIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get ordered manual product recommendations

Returns manual recommendations for the resolved shop in maintained order. Only products assigned to that shop can appear.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace ordered manual product recommendations

Replaces the complete manual recommendation set for the resolved shop. Array order defines display order, an empty array clears the set, and at most 20 products are accepted. Self-relations and products outside the resolved shop use the same validation response.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
productIds
required
Array of integers <= 20 items unique [ items [ 1 .. 2147483647 ] ]

Complete ordered manual recommendation set for the resolved shop.

Responses

Request samples

Content type
application/json
{
  • "productIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a product shop price override

Replaces shop-specific base-price override data for one assigned, active, non-primary shop. The target shop is taken from the path and must be assigned to the authenticated API client; this endpoint does not accept a separate shopId query parameter.

price replaces all quantity-one override rows, including scheduled or inactive rows at that threshold, while leaving higher thresholds untouched. priceTiers completely replaces all override rows in the selected currency and may start above quantity one. { "inherit": true } removes every override tier in that currency and restores canonical fallback. Exactly one of these three fields is required.

The optional currency query parameter selects an active currency; otherwise the target shop's default currency is used. The response contains active, non-scheduled stored tiers, not the fully resolved effective price. Use the product prices endpoint with the target shop context for effective and time-dependent pricing.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
= 1 properties
One of
= 1 properties
inherit
required
boolean

Remove all overrides in the selected currency.

Value: true
object (ProductCreatePrice)

Replace all quantity-one shop override rows.

Array of objects (ProductUpdatePriceTier) [ 1 .. 100 ] items

Complete replacement for shop override tiers in the selected currency.

Responses

Request samples

Content type
application/json
{
  • "priceTiers": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Create a product variant

Creates an initially inactive variant for a product assigned to the resolved shop. Variant master data remains global; the shop context is only the authorization and presentation boundary. sku is globally unique. options can atomically assign one product-enabled value per group; its array order is the returned display order. Media, measurements, translations, custom fields, and optional canonical variant prices can be authored in the same request. Shop and price-list overrides use their explicit pricing operations.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
sku
required
string [ 1 .. 120 ] characters
ean
string or null^(?:|[0-9]{8}|[0-9]{12,14})$
deliveryTimeId
integer >= 0
name
string or null <= 255 characters
shortName
string or null <= 50 characters
minimumOrderQuantity
integer >= 0
description
string or null
shortDescription
string or null

May contain markup; rendered text is limited to 255 characters.

packagingUnit
string or null <= 120 characters
object (VariantMeasurementWrite) non-empty

Variant-specific measurement overrides. Omitted properties remain unchanged. A null numeric value, or zero for measurementUnitId, removes that override and restores parent-product inheritance.

object (ConnectorCustomFieldWriteValues) <= 100 properties

Complete replacement of all active connector-visible custom-field values for the entity in the resolved shop. Keys are technical custom- field keys. Null clears a scalar value; an empty array clears a multi-select value. Definitions not visible to connectors cannot be addressed and remain unchanged.

manufacturerNumber
string or null <= 120 characters
sortOrder
integer >= 0
Default: 0
isDefault
boolean
Default: false
active
boolean
Default: false
Array of objects (VariantMutationOption) <= 20 items
object (ProductCreatePrice)

Optional canonical quantity-one variant price.

Array of objects (ProductUpdatePriceTier) <= 100 items

Optional canonical variant tiers in the resolved currency. The first threshold may be greater than one. An empty array stores no variant price rows and therefore inherits parent-product pricing.

Responses

Request samples

Content type
application/json
{
  • "sku": "string",
  • "ean": "string",
  • "deliveryTimeId": 0,
  • "name": "string",
  • "shortName": "string",
  • "minimumOrderQuantity": 0,
  • "description": "string",
  • "shortDescription": "string",
  • "packagingUnit": "string",
  • "measurements": {
    },
  • "customFields": {
    },
  • "manufacturerNumber": "string",
  • "sortOrder": 0,
  • "isDefault": false,
  • "active": false,
  • "options": [
    ],
  • "price": {
    },
  • "priceTiers": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List product variants

Returns variants of products assigned to the resolved shop. The collection defaults to active variants of active products. Use active=false for inactive variants or active=all to remove variant and parent-product active-state filtering. q performs a case-insensitive substring search across the effective name, short name, SKU/article number, EAN, manufacturer number, and short description. Effective values include the documented language and parent-product fallbacks; the long description is not searched. Prices and quantity tiers use the selected currency and optional price list. Availability is calculated for the concrete variant at the shop's default inventory location and accounts for active reservations.

Use productId to restrict the collection to one parent product.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

sort
string^-?(id|productId|name|sku|sortOrder|updatedAt...
Default: "productId,sortOrder,id"
Example: sort=productId,sortOrder,id

Comma-separated variant fields. Supported fields are id, productId, name, sku, sortOrder, and updatedAt. Prefix a field with - for descending order.

productId
integer >= 1
Example: productId=42

Restricts the collection to variants belonging to this shop-assigned parent product. The active parameter controls active-state filtering.

q
string <= 200 characters
Examples:
  • q=red -

Case-insensitive substring search across the effective localized name, short name, SKU/article number, EAN, manufacturer number, and short description. Effective values include variant, language, and parent product fallbacks. The long description is not searched.

active
string
Default: "true"
Enum: "true" "false" "all"
Examples:
  • active=all -

Controls variant active-state filtering. true returns active variants of active products, false returns inactive variants, and all removes both variant and parent-product active-state filtering.

updatedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedAfter=2026-07-01T00:00:00Z

Exclusive lower boundary for the variant's effective updatedAt. Only variants with updatedAt > updatedAfter are returned.

updatedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedBefore=2026-08-01T00:00:00Z

Exclusive upper boundary for the variant's effective updatedAt. Only variants with updatedAt < updatedBefore are returned. When both boundaries are present, this value must be later than updatedAfter.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get a product variant

Returns one variant of a product assigned to the resolved shop, independently of the variant or parent-product active state. The active response field exposes the variant state. All inheritable fields are returned as effective values, including fallbacks from the parent product. The media gallery uses active variant images when available and otherwise falls back to the parent product gallery. SEO metadata and the canonical path belong to the parent product because variants do not have independent storefront URLs. Connector-visible variant custom fields are resolved for the selected shop and language.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Partially update a product variant

Partially updates global variant base data after verifying that its parent product is assigned to the resolved shop. Omitted fields remain unchanged. Use active: false to safely deactivate a variant that has already been used operationally. Zero clears deliveryTimeId or an inherited minimumOrderQuantity override. When supplied, options completely replaces the variant combination and its order; an empty array removes all option assignments. price replaces only the canonical quantity-one tier. priceTiers completely replaces canonical tiers in the resolved currency; an empty array restores parent-product price inheritance.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
non-empty
sku
string [ 1 .. 120 ] characters
ean
string or null^(?:|[0-9]{8}|[0-9]{12,14})$
deliveryTimeId
integer >= 0

Zero clears the variant-specific delivery time.

name
string or null <= 255 characters
shortName
string or null <= 50 characters
minimumOrderQuantity
integer >= 0

Zero restores the parent-product fallback.

description
string or null
shortDescription
string or null

May contain markup; rendered text is limited to 255 characters.

packagingUnit
string or null <= 120 characters
object (VariantMeasurementWrite) non-empty

Variant-specific measurement overrides. Omitted properties remain unchanged. A null numeric value, or zero for measurementUnitId, removes that override and restores parent-product inheritance.

object (ConnectorCustomFieldWriteValues) <= 100 properties

Complete replacement of all active connector-visible custom-field values for the entity in the resolved shop. Keys are technical custom- field keys. Null clears a scalar value; an empty array clears a multi-select value. Definitions not visible to connectors cannot be addressed and remain unchanged.

manufacturerNumber
string or null <= 120 characters
sortOrder
integer >= 0
isDefault
boolean
active
boolean
Array of objects (VariantMutationOption) <= 20 items
object (ProductCreatePrice)

Replace only the canonical quantity-one variant tier.

Array of objects (ProductUpdatePriceTier) <= 100 items

Complete replacement for canonical variant tiers in the resolved currency. The first threshold may be greater than one. An empty array removes all own tiers and restores parent-product fallback.

Responses

Request samples

Content type
application/json
{
  • "sku": "string",
  • "ean": "string",
  • "deliveryTimeId": 0,
  • "name": "string",
  • "shortName": "string",
  • "minimumOrderQuantity": 0,
  • "description": "string",
  • "shortDescription": "string",
  • "packagingUnit": "string",
  • "measurements": {
    },
  • "customFields": {
    },
  • "manufacturerNumber": "string",
  • "sortOrder": 0,
  • "isDefault": true,
  • "active": true,
  • "options": [
    ],
  • "price": {
    },
  • "priceTiers": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete an unused product variant

Permanently deletes a variant only while it has no cart, order, inventory-movement, or inventory-reservation history. A used variant returns 409 variant_in_use and must be deactivated with PATCH instead. This bounded unused-record cleanup is the only destructive catalog entity deletion exposed in Phase 2.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get resolved variant prices

Returns the current resolved price and effective quantity tiers for one concrete variant whose parent product is assigned to the resolved shop, regardless of the variant or parent-product active state. Resolution applies a variant price-list override, then a parent-product price-list override, then the resolved variant base price and applicable marketing price actions. Missing price-list rows fall back to the resolved base price.

This compact response represents the concrete variant only. It does not expose raw price records or price-list override rows.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List raw variant price-list rows

Returns only price-list rows stored for the concrete variant. It does not include inherited product rows or resolve any fallback. The parent product must be visible in the selected shop; rows remain global.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$

Optional ISO currency filter; omit it to include every currency.

priceListId
integer >= 1

Optional global price-list filter; omit it to include every price list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a variant price-list row

Creates one global variant override row without materializing product inheritance.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
priceListId
required
integer >= 1
minQuantity
integer >= 1
Default: 1
amount
required
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "priceListId": 1,
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a variant price-list row

Updates mutable values while preserving row identity, price list, and currency.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
non-empty
minQuantity
integer >= 1
amount
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a variant price-list row

Deletes the selected raw variant price-list row without changing canonical prices or other quantity tiers.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace a shop-specific variant price override

Replaces or removes variant base-price override tiers for one assigned, active, non-primary shop and selected currency. The path shop is the authorization boundary and must be assigned to the API client. Supply exactly one of price, priceTiers, or inherit. The first tier may begin above quantity one. inherit: true removes every variant shop override in the selected currency and restores canonical variant or parent-product fallback resolution.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
= 1 properties
One of
= 1 properties
inherit
required
boolean

Remove all overrides in the selected currency.

Value: true
object (ProductCreatePrice)

Replace all quantity-one shop override rows.

Array of objects (ProductUpdatePriceTier) [ 1 .. 100 ] items

Complete replacement for shop override tiers in the selected currency.

Responses

Request samples

Content type
application/json
{
  • "inherit": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace a global variant price-list override

Replaces or removes quantity tiers for one variant and global price list in the resolved currency. Price lists are global master data; the resolved shop verifies access to the variant but does not scope the stored override. Supply exactly one of price, priceTiers, or inherit. Override amounts inherit the amount type from resolved base pricing. Writing amounts therefore requires an existing resolved base price, while inherit: true is always allowed and restores normal base-price fallback.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

priceListId
required
integer >= 1
Example: 8

Positive ID of a global price list.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
= 1 properties
One of
= 1 properties
inherit
required
boolean

Remove all override tiers for this variant, list, and currency.

Value: true
object (VariantPriceListOverridePrice)

Replace the quantity-one price-list override.

Array of objects (VariantPriceListOverridePriceTier) [ 1 .. 100 ] items

Complete replacement for the selected price-list override tiers.

Responses

Request samples

Content type
application/json
{
  • "inherit": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Add an image to a product variant

Adds one active image to a variant whose parent product is assigned to the resolved shop. Send JSON with mediaAssetId to reuse an existing media-library image, or send one file as multipart/form-data to upload and assign a new image in one request.

Existing variant images, downloads, and other media roles are preserved. Without sortOrder, a new image is appended after the current variant images. Repeating an existing assignment is idempotent and returns 200; a newly created assignment returns 201. The response is the authoritative public variant detail.

Supported uploads are JPG, PNG, GIF, WebP, AVIF, and SVG. The configured media upload-size limit applies.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema:
required
mediaAssetId
required
integer >= 1

Existing active image asset to assign to the variant.

sortOrder
integer [ 0 .. 2147483647 ]

Optional gallery order; lower values are returned first.

Responses

Request samples

Content type
{
  • "mediaAssetId": 91,
  • "sortOrder": 20
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace and order a variant image gallery

Replaces the variant's complete image assignment with the ordered mediaAssetIds array. Every ID must reference a distinct active image; at most 100 images may be supplied. The first ID becomes the primary variant image. Repeating the same ordered array is idempotent.

Downloads and other variant media roles are preserved. An empty array removes every variant-specific image. Public variant reads then fall back to the parent product gallery; inherited product images are not copied to the variant.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
mediaAssetIds
required
Array of integers <= 100 items unique [ items [ 1 .. 2147483647 ] ]

Complete ordered set of active images assigned to the variant.

Responses

Request samples

Content type
application/json
{
  • "mediaAssetIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Remove one image from a product variant

Removes only the selected variant image assignment. The media-library asset itself and all other usages remain unchanged. Removing the last variant-specific image restores the parent product gallery fallback in public variant reads.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

mediaAssetId
required
integer >= 1
Example: 91

Positive media-asset identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List variant groups

Returns the global variant-group registry in the resolved language, including each localized value and inactive records. The selected shop authorizes and resolves language context, but does not filter the registry. This endpoint exposes value master data, not product-specific variant combinations or assignment usage.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List categories

Returns categories assigned to the resolved shop. The collection defaults to active categories; use active=false or active=all for other states. q performs a case-insensitive substring search across the effective localized name and description. Category and parent names are resolved for the requested language with the shop default language and category master data as fallbacks. Collection items intentionally contain compact master data without descriptions, media, or SEO metadata.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

sort
string^-?(id|name|sortOrder|updatedAt)(,-?(id|name|...
Default: "sortOrder,id"
Example: sort=-updatedAt,name

Comma-separated category fields. Supported fields are id, name, sortOrder, and updatedAt. Prefix a field with - for descending order.

q
string <= 200 characters
Examples:
  • q=running -

Case-insensitive substring search across the effective localized category name and description. The description is searchable even though it is returned only by the detail endpoint.

active
string
Default: "true"
Enum: "true" "false" "all"
Examples:
  • active=false -

Filters by category active state. true returns active categories, false returns inactive categories, and all returns both states.

updatedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedAfter=2026-07-01T00:00:00Z

Exclusive lower boundary for updatedAt. Only categories with updatedAt > updatedAfter are returned.

updatedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedBefore=2026-08-01T00:00:00Z

Exclusive upper boundary for updatedAt. Only categories with updatedAt < updatedBefore are returned. When both boundaries are present, this value must be later than updatedAfter.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a category

Creates one shared category master record, stores its localized text and media references in the resolved language, and assigns it to the resolved shop by default. shopIds may assign the category to several active shops, but every requested shop must be authorized for the API client and the resolved shop must remain included.

Parent, order, default product sorting, and storefront display values are stored as shop-assignment data. A parent must already be assigned to every selected shop. New categories default to inactive. Category names are not unique; every successful request creates a new category. Automatic slugs are created for every requested shop. An optional seo object may set a manual slug and localized metadata.

Authentication with the catalog:write scope is required.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Category name in the resolved request language.

description
string or null
active
boolean
Default: false
parentCategoryId
integer or null [ 0 .. 2147483647 ]
Default: 0

Zero or null creates a root category.

sortOrder
integer or null [ 0 .. 2147483647 ]

Omit or use null to append after the selected parent in the resolved shop.

defaultProductSort
string
Default: "default"
Enum: "default" "name_asc" "price_asc" "price_desc" "newest"
storefrontDisplayMode
string
Default: "automatic"
Enum: "automatic" "subcategories_products" "products"
childCategoryDisplayVariant
string
Default: "grid"
Enum: "grid" "cards" "tiles"
iconMediaAssetId
integer or null [ 0 .. 2147483647 ]

Zero or null leaves the localized icon unset.

bannerMediaAssetId
integer or null [ 0 .. 2147483647 ]

Zero or null leaves the localized banner unset.

shopIds
Array of integers [ 1 .. 100 ] items [ items [ 1 .. 2147483647 ] ]

Active API-authorized shop assignments. Defaults to the resolved shop and must include it when supplied.

object (CatalogSeoWrite) non-empty

SEO changes for the resolved language. A non-empty slug creates a normalized manual canonical slug. slug: null resets the canonical to automatic generation from the localized name. Changing a canonical preserves its former value as a 301 history entry. Metadata properties are partial; null or an empty string clears the supplied property.

Responses

Request samples

Content type
application/json
{
  • "name": "Running shoes",
  • "description": "Shoes designed for running.",
  • "active": false,
  • "parentCategoryId": 3,
  • "defaultProductSort": "price_asc",
  • "storefrontDisplayMode": "products",
  • "childCategoryDisplayVariant": "cards",
  • "iconMediaAssetId": 31,
  • "bannerMediaAssetId": 32,
  • "seo": {
    },
  • "shopIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a category

Returns one category when it is assigned to the resolved shop, independently of its active state. The detail adds its localized description, icon and banner references, SEO metadata, and connector-visible category custom fields. The active response field exposes the category state. Unassigned categories are not exposed.

Authorizations:
ApiKeyAuth
path Parameters
categoryId
required
integer >= 1
Example: 12

Positive category identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a category

Partially updates a category assigned to the resolved shop. Omitted fields remain unchanged. Name, description, icon, and banner apply to the resolved language; active changes global category master data; parent, order, default product sorting, and storefront display fields apply to the resolved shop.

shopIds replaces assignments only among active shops authorized for the API client. Existing assignments outside that mutable set are preserved, and the resolved shop must remain assigned. Newly assigned shops inherit the resolved shop's current hierarchy and display settings. A parent must be assigned to every newly affected shop and must not create a hierarchy cycle.

Empty description clears the localized description. Zero clears an icon, banner, or parent. Renaming updates automatic slugs across the assigned shops authorized for the client while manual slugs remain stable. seo.slug sets a manual slug and null resets it to automatic; prior canonical slugs remain 301 history. Custom fields are not changed. Repeating the same request is idempotent. Use active: false for reversible deactivation; the public API exposes no destructive category DELETE because hierarchy, SEO, product, and cross-shop references must be preserved. Authentication with the catalog:write scope is required.

Authorizations:
ApiKeyAuth
path Parameters
categoryId
required
integer >= 1
Example: 12

Positive category identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 255 ] characters

Category name in the resolved request language.

description
string
active
boolean
parentCategoryId
integer [ 0 .. 2147483647 ]

Zero makes the category a root in the resolved shop.

sortOrder
integer [ 0 .. 2147483647 ]
defaultProductSort
string
Enum: "default" "name_asc" "price_asc" "price_desc" "newest"
storefrontDisplayMode
string
Enum: "automatic" "subcategories_products" "products"
childCategoryDisplayVariant
string
Enum: "grid" "cards" "tiles"
iconMediaAssetId
integer [ 0 .. 2147483647 ]

Active image media ID; zero clears the localized icon.

bannerMediaAssetId
integer [ 0 .. 2147483647 ]

Active image media ID; zero clears the localized banner.

shopIds
Array of integers [ 1 .. 100 ] items [ items [ 1 .. 2147483647 ] ]

Complete desired assignment list among active API-authorized shops. Must include the resolved shop. Existing hidden or inactive assignments are preserved.

object (CatalogSeoWrite) non-empty

SEO changes for the resolved language. A non-empty slug creates a normalized manual canonical slug. slug: null resets the canonical to automatic generation from the localized name. Changing a canonical preserves its former value as a 301 history entry. Metadata properties are partial; null or an empty string clears the supplied property.

Responses

Request samples

Content type
application/json
{
  • "name": "Running and trail shoes",
  • "description": "Shoes designed for running and trail use.",
  • "active": true,
  • "parentCategoryId": 3,
  • "sortOrder": 30,
  • "defaultProductSort": "name_asc",
  • "storefrontDisplayMode": "products",
  • "childCategoryDisplayVariant": "tiles",
  • "iconMediaAssetId": 41,
  • "seo": {
    },
  • "shopIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List manufacturers

Returns manufacturers assigned to the resolved shop in the resolved language. Manufacturers are shared catalog master data; the explicit shop assignment is the visibility boundary. The collection defaults to active manufacturers. q performs a case-insensitive substring search across the effective localized name and description.

updatedAt includes relevant manufacturer, selected-shop assignment, and selected-language fallback changes. The response does not expose assignment lists, product-reference counts, or raw translations.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

sort
string^-?(id|name|updatedAt)(,-?(id|name|updatedAt)...
Default: "name,id"
Example: sort=-updatedAt,name

Comma-separated manufacturer fields. Supported fields are id, name, and updatedAt. Prefix a field with - for descending order.

q
string <= 200 characters
Examples:
  • q=example -

Case-insensitive substring search across the effective localized manufacturer name and description.

active
string
Default: "true"
Enum: "true" "false" "all"
Examples:
  • active=false -

Filters by manufacturer active state. true returns active manufacturers, false returns inactive manufacturers, and all returns both states.

updatedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedAfter=2026-08-01T00:00:00Z

Exclusive lower boundary for the manufacturer's effective updatedAt. Only manufacturers with updatedAt > updatedAfter are returned.

updatedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedBefore=2026-08-02T00:00:00Z

Exclusive upper boundary for the manufacturer's effective updatedAt. Only manufacturers with updatedAt < updatedBefore are returned. When both boundaries are present, this value must be later than updatedAfter.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a manufacturer

Creates shared manufacturer master data and its translation in the resolved language. New manufacturers default to inactive. shopIds defaults to the resolved shop; every submitted shop must be active, assigned to the API client, and include the resolved shop.

logoMediaAssetId must reference an active image. customFields, when supplied, authoritatively replaces values for active manufacturer fields marked connector-visible in the resolved shop. Authentication with the catalog:write scope is required.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Manufacturer name in the resolved request language.

description
string or null
active
boolean
Default: false
shopIds
Array of integers [ 1 .. 100 ] items [ items [ 1 .. 2147483647 ] ]

Active API-authorized assignments. Defaults to the resolved shop and must include it when supplied.

logoMediaAssetId
integer or null [ 0 .. 2147483647 ]

Active image ID; zero or null leaves the logo unset.

object (ConnectorCustomFieldWriteValues) <= 100 properties

Complete replacement of all active connector-visible custom-field values for the entity in the resolved shop. Keys are technical custom- field keys. Null clears a scalar value; an empty array clears a multi-select value. Definitions not visible to connectors cannot be addressed and remain unchanged.

Responses

Request samples

Content type
application/json
{
  • "name": "Example manufacturer",
  • "description": "A manufacturer of example products.",
  • "active": false,
  • "shopIds": [
    ],
  • "logoMediaAssetId": 41,
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a manufacturer

Returns one manufacturer when it is assigned to the resolved shop, independently of its active state. The detail adds the active manufacturer logo and connector-visible manufacturer custom fields. The logo is returned as a public catalog media reference. An unassigned manufacturer is not exposed.

Authorizations:
ApiKeyAuth
path Parameters
manufacturerId
required
integer >= 1
Example: 5

Positive manufacturer identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a manufacturer

Partially updates a manufacturer assigned to the resolved shop. Name and description apply to the resolved language; active changes shared master data. Empty description clears the localized value. Zero clears the logo while preserving every non-logo media usage.

shopIds authoritatively replaces assignments only among active shops authorized for the API client. Existing hidden or inactive assignments are preserved, and the resolved shop must remain assigned. Supplying customFields authoritatively replaces only connector-visible values in the resolved shop. Omitted fields remain unchanged, and identical retries have the same result. Use active: false for reversible deactivation; the public API exposes no destructive manufacturer DELETE because product and cross-shop references must be preserved. Authentication with catalog:write is required.

Authorizations:
ApiKeyAuth
path Parameters
manufacturerId
required
integer >= 1
Example: 5

Positive manufacturer identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 255 ] characters

Manufacturer name in the resolved request language.

description
string

Empty string clears the localized description.

active
boolean
shopIds
Array of integers [ 1 .. 100 ] items [ items [ 1 .. 2147483647 ] ]

Complete desired assignment set among active API-authorized shops. Must include the resolved shop.

logoMediaAssetId
integer [ 0 .. 2147483647 ]

Active image ID; zero clears the manufacturer logo.

object (ConnectorCustomFieldWriteValues) <= 100 properties

Complete replacement of all active connector-visible custom-field values for the entity in the resolved shop. Keys are technical custom- field keys. Null clears a scalar value; an empty array clears a multi-select value. Definitions not visible to connectors cannot be addressed and remain unchanged.

Responses

Request samples

Content type
application/json
{
  • "name": "Updated manufacturer",
  • "active": true,
  • "shopIds": [
    ],
  • "logoMediaAssetId": 51,
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List product markings

Returns the global product-marking registry in the resolved language, including inactive records so integrations can retain stable marking references. The selected shop authorizes and resolves language context, but does not filter the registry. Product responses separately expose only current active marking assignments for the selected shop.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List product specifications

Returns the global product-specification definition registry in the resolved language, including its option values. Definitions and options are returned regardless of active state so integrations can retain stable references. The selected shop authorizes and resolves language context, but does not filter the registry.

Product details separately expose only assigned values whose set item, definition, and selected option remain storefront-visible and active.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List measurement units

Returns the global measurement-unit master-data registry in the resolved language. The selected shop authorizes and resolves the language context, but does not filter the registry. Both active and inactive units are returned so integrations can preserve references to existing product data.

The response contains resolved public values only and never exposes raw translations or administrative configuration.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List delivery times

Returns the global delivery-time master-data registry in the resolved language. The selected shop authorizes and resolves the language context, but does not filter the registry. Each record contains its normalized unit plus the inclusive minimum and maximum delivery-time range.

The response contains resolved public values only and never exposes raw translations or administrative configuration.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Pricing

Resolved pricing and global price-list discovery

Get resolved product prices

Returns the current resolved price and effective quantity tiers for one product assigned to the resolved shop, regardless of its active state. Resolution applies the selected shop's base-price override, the optional global price-list override, and applicable marketing price actions. Missing price-list rows fall back to the resolved base price.

This compact response represents the main product only. It does not expose variant prices, raw price records, or price-list override rows.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List raw product price-list rows

Returns stored product price-list rows without resolving base-price fallback, shop overrides, inheritance, or marketing price actions. The selected shop authorizes product visibility only; rows are global. Omit currency and priceListId to return all stored rows.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$

Optional ISO currency filter; omit it to include every currency.

priceListId
integer >= 1

Optional global price-list filter; omit it to include every price list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a product price-list row

Creates one global product price-list override row in the resolved currency. Price list, currency, and minimum quantity must be unique.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
priceListId
required
integer >= 1
minQuantity
integer >= 1
Default: 1
amount
required
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "priceListId": 1,
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a product price-list row

Updates mutable values while preserving row identity, price list, and currency.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
non-empty
minQuantity
integer >= 1
amount
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a product price-list row

Deletes the selected raw product price-list row without changing canonical prices or other quantity tiers.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a product shop price override

Replaces shop-specific base-price override data for one assigned, active, non-primary shop. The target shop is taken from the path and must be assigned to the authenticated API client; this endpoint does not accept a separate shopId query parameter.

price replaces all quantity-one override rows, including scheduled or inactive rows at that threshold, while leaving higher thresholds untouched. priceTiers completely replaces all override rows in the selected currency and may start above quantity one. { "inherit": true } removes every override tier in that currency and restores canonical fallback. Exactly one of these three fields is required.

The optional currency query parameter selects an active currency; otherwise the target shop's default currency is used. The response contains active, non-scheduled stored tiers, not the fully resolved effective price. Use the product prices endpoint with the target shop context for effective and time-dependent pricing.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
= 1 properties
One of
= 1 properties
inherit
required
boolean

Remove all overrides in the selected currency.

Value: true
object (ProductCreatePrice)

Replace all quantity-one shop override rows.

Array of objects (ProductUpdatePriceTier) [ 1 .. 100 ] items

Complete replacement for shop override tiers in the selected currency.

Responses

Request samples

Content type
application/json
{
  • "priceTiers": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get resolved variant prices

Returns the current resolved price and effective quantity tiers for one concrete variant whose parent product is assigned to the resolved shop, regardless of the variant or parent-product active state. Resolution applies a variant price-list override, then a parent-product price-list override, then the resolved variant base price and applicable marketing price actions. Missing price-list rows fall back to the resolved base price.

This compact response represents the concrete variant only. It does not expose raw price records or price-list override rows.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List raw variant price-list rows

Returns only price-list rows stored for the concrete variant. It does not include inherited product rows or resolve any fallback. The parent product must be visible in the selected shop; rows remain global.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$

Optional ISO currency filter; omit it to include every currency.

priceListId
integer >= 1

Optional global price-list filter; omit it to include every price list.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a variant price-list row

Creates one global variant override row without materializing product inheritance.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
priceListId
required
integer >= 1
minQuantity
integer >= 1
Default: 1
amount
required
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "priceListId": 1,
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a variant price-list row

Updates mutable values while preserving row identity, price list, and currency.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
non-empty
minQuantity
integer >= 1
amount
string^[0-9]{1,12}(\.[0-9]{1,4})?$
compareAtAmount
string or null^[0-9]{1,12}(\.[0-9]{1,4})?$

Responses

Request samples

Content type
application/json
{
  • "minQuantity": 1,
  • "amount": "string",
  • "compareAtAmount": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a variant price-list row

Deletes the selected raw variant price-list row without changing canonical prices or other quantity tiers.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

priceListPriceId
required
integer >= 1
Example: 91

Positive raw price-list row ID returned by the matching product or variant endpoint.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace a shop-specific variant price override

Replaces or removes variant base-price override tiers for one assigned, active, non-primary shop and selected currency. The path shop is the authorization boundary and must be assigned to the API client. Supply exactly one of price, priceTiers, or inherit. The first tier may begin above quantity one. inherit: true removes every variant shop override in the selected currency and restores canonical variant or parent-product fallback resolution.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
= 1 properties
One of
= 1 properties
inherit
required
boolean

Remove all overrides in the selected currency.

Value: true
object (ProductCreatePrice)

Replace all quantity-one shop override rows.

Array of objects (ProductUpdatePriceTier) [ 1 .. 100 ] items

Complete replacement for shop override tiers in the selected currency.

Responses

Request samples

Content type
application/json
{
  • "inherit": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace a global variant price-list override

Replaces or removes quantity tiers for one variant and global price list in the resolved currency. Price lists are global master data; the resolved shop verifies access to the variant but does not scope the stored override. Supply exactly one of price, priceTiers, or inherit. Override amounts inherit the amount type from resolved base pricing. Writing amounts therefore requires an existing resolved base price, while inherit: true is always allowed and restores normal base-price fallback.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

priceListId
required
integer >= 1
Example: 8

Positive ID of a global price list.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
= 1 properties
One of
= 1 properties
inherit
required
boolean

Remove all override tiers for this variant, list, and currency.

Value: true
object (VariantPriceListOverridePrice)

Replace the quantity-one price-list override.

Array of objects (VariantPriceListOverridePriceTier) [ 1 .. 100 ] items

Complete replacement for the selected price-list override tiers.

Responses

Request samples

Content type
application/json
{
  • "inherit": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List price lists

Returns the global price-list catalog in the resolved language. The selected shop authorizes and resolves the language context, but does not filter the global price lists. A price list is an optional pricing override layer; this endpoint returns metadata only, never product or variant price overrides.

Use an item ID as priceListId when requesting context-sensitive catalog pricing from product or variant endpoints.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a price list

Creates a global optional pricing layer and stores name for the resolved language. The selected shop supplies authorization and language context; it does not own or filter the price list.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Request Body schema: application/json
required
name
required
string [ 1 .. 120 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a price list

Returns localized metadata for one global price list. The selected shop authorizes and resolves the language context, but does not scope price-list availability. The response does not expose translations or product and variant price overrides.

Authorizations:
ApiKeyAuth
path Parameters
priceListId
required
integer >= 1
Example: 8

Positive ID of a global price list.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a price list

Replaces the price-list name in the resolved language. A default-language update also changes the canonical fallback name; other languages change only their translation.

Authorizations:
ApiKeyAuth
path Parameters
priceListId
required
integer >= 1
Example: 8

Positive ID of a global price list.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Request Body schema: application/json
required
name
required
string [ 1 .. 120 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Inventory

Current operational inventory snapshots and controlled writes. Reservations remain lifecycle-owned by cart, checkout, payment, and order services; direct reservation CRUD is intentionally not exposed.

List active inventory locations

Returns active global physical inventory locations and identifies the configured default. Locations are not shop-owned, so this discovery endpoint requires inventory:read but no Commerce request context.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get simple-product inventory

Returns the current operational inventory snapshot for one simple product assigned to the resolved shop. The selected shop is the product-visibility boundary; inventory locations and physical stock are global. When locationId is omitted, the configured default location is used. reservedQuantity includes all active reservations for the physical product stock at the selected location.

Products with variants return 409 inventory_managed_by_variants. Use the variant inventory endpoint for those products. Inventory movements, internal inventory IDs, notes, and actor details are not exposed by this snapshot endpoint.

Authentication with the inventory:read scope and Commerce request context is required.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

locationId
integer >= 1
Example: locationId=4

Active global inventory-location ID. Snapshot endpoints use the configured default when omitted; movement collections include all locations when omitted.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List simple-product inventory movements

Returns newest-first physical-stock movements for one shop-visible simple product across all global locations, or one active location selected by locationId.

reference and idempotencyKey are returned and filterable only for API inventory adjustments authored by the currently authenticated API client. Other movements remain visible with their quantities, location, reason, and timestamp, but their lifecycle reference is redacted. Internal notes, actors, fingerprints, and idempotency scopes are never exposed. Authentication with inventory:read is required.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

locationId
integer >= 1
Example: locationId=4

Active global inventory-location ID. Snapshot endpoints use the configured default when omitted; movement collections include all locations when omitted.

createdAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: createdAfter=2026-09-01T00:00:00Z

Exclusive lower UTC boundary for movement creation time.

createdBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: createdBefore=2026-10-01T00:00:00Z

Exclusive upper UTC boundary; must be later than createdAfter.

reason
string [ 1 .. 50 ] characters ^[a-z][a-z0-9._-]*$
Example: reason=erp_sync

Exact public technical reason; API storage prefixes are normalized away.

reference
string [ 1 .. 120 ] characters
Example: reference=ERP-501

Exact external reference. Searches only API inventory adjustments authored by the authenticated API client.

idempotencyKey
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: idempotencyKey=inventory-request-501

Exact idempotency key. Searches only API inventory adjustments authored by the authenticated API client.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Update product availability flags

Partially updates backorderAllowed and alwaysAvailable for the shop-visible product inventory scope. At least one field is required; omitted fields retain their stored values. Product flags remain writable for products with variants because product alwaysAvailable is the existing variant fallback.

This target-state update is idempotent without an Idempotency-Key. It does not change stock or create an inventory movement. Authentication with inventory:write is required.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
non-empty
backorderAllowed
boolean
alwaysAvailable
boolean

Responses

Request samples

Content type
application/json
{
  • "backorderAllowed": true,
  • "alwaysAvailable": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Adjust simple-product inventory

Atomically adds quantityDelta to the physical on-hand stock of one simple product assigned to the resolved shop. A positive delta adds stock and a negative delta removes stock. The operation uses the globally configured default inventory location; the selected shop is the product-visibility boundary and does not create shop-specific physical stock.

The resulting on-hand quantity cannot be lower than active reservations. Products with active variants must be adjusted through their variant inventory and return 409 inventory_managed_by_variants here.

Idempotency-Key is required and scoped to the authenticated API client. The first successful booking returns 201. Repeating the exact normalized request with the same key does not book another movement and returns 200 with idempotentReplay: true. Reusing the key for different adjustment data returns 409 idempotency_conflict.

Authentication with the inventory:write scope and Commerce request context is required.

Authorizations:
ApiKeyAuth
path Parameters
productId
required
integer [ 1 .. 2147483647 ]
Example: 42

Positive product identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

header Parameters
Idempotency-Key
required
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: inventory-request-501

Caller-generated identifier that makes one mutation safe to retry. Keys are scoped to the authenticated API client and must not be reused for different normalized request data.

Request Body schema: application/json
required
quantityDelta
required
number decimal places <= 4 [ -1000000000000000 .. 1000000000000000 ]

Signed amount added to the current physical on-hand stock.

reason
required
string [ 1 .. 35 ] characters ^[a-z][a-z0-9._-]{0,34}$

Technical reason key stored with the inventory movement.

reference
string <= 120 characters

Optional external reference such as an ERP transaction ID.

note
string <= 1000 characters

Optional human-readable audit note.

Responses

Request samples

Content type
application/json
{
  • "quantityDelta": -2,
  • "reason": "erp_sync",
  • "reference": "ERP-501",
  • "note": "Warehouse correction"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get product-variant inventory

Returns the current operational inventory snapshot for one product variant whose parent product is assigned to the resolved shop. The selected shop is the product-visibility boundary; the inventory locations and physical stock are global. When locationId is omitted, the configured default location is used. reservedQuantity includes all active reservations for that physical variant stock at the selected location.

Inventory movements, internal inventory IDs, notes, and actor details are not exposed by this snapshot endpoint. Authentication with the inventory:read scope and Commerce request context is required.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

locationId
integer >= 1
Example: locationId=4

Active global inventory-location ID. Snapshot endpoints use the configured default when omitted; movement collections include all locations when omitted.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List product-variant inventory movements

Returns newest-first physical-stock movements for one product variant whose parent product is visible in the selected shop. The location, pagination, timestamp, reason, reference, idempotency, redaction, and API-client ownership rules match the product movement endpoint.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

locationId
integer >= 1
Example: locationId=4

Active global inventory-location ID. Snapshot endpoints use the configured default when omitted; movement collections include all locations when omitted.

createdAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: createdAfter=2026-09-01T00:00:00Z

Exclusive lower UTC boundary for movement creation time.

createdBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: createdBefore=2026-10-01T00:00:00Z

Exclusive upper UTC boundary; must be later than createdAfter.

reason
string [ 1 .. 50 ] characters ^[a-z][a-z0-9._-]*$
Example: reason=erp_sync

Exact public technical reason; API storage prefixes are normalized away.

reference
string [ 1 .. 120 ] characters
Example: reference=ERP-501

Exact external reference. Searches only API inventory adjustments authored by the authenticated API client.

idempotencyKey
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: idempotencyKey=inventory-request-501

Exact idempotency key. Searches only API inventory adjustments authored by the authenticated API client.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Update product-variant availability flags

Partially updates backorderAllowed and alwaysAvailable for the exact shop-visible variant inventory scope. At least one field is required; omitted fields retain their stored values. The target-state update is idempotent without an Idempotency-Key, does not change stock, and does not create an inventory movement. Authentication with inventory:write is required.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Request Body schema: application/json
required
non-empty
backorderAllowed
boolean
alwaysAvailable
boolean

Responses

Request samples

Content type
application/json
{
  • "backorderAllowed": true,
  • "alwaysAvailable": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Adjust product-variant inventory

Atomically adds quantityDelta to the physical on-hand stock of one product variant whose parent product is assigned to the resolved shop. A positive delta adds stock and a negative delta removes stock. The operation uses the globally configured default inventory location; the selected shop is the product-visibility boundary and does not create shop-specific physical stock.

The resulting on-hand quantity cannot be lower than active reservations for this exact variant inventory scope.

Idempotency-Key is required and scoped to the authenticated API client. The first successful booking returns 201. Repeating the exact normalized request with the same key does not book another movement and returns 200 with idempotentReplay: true. Reusing the key for different adjustment data returns 409 idempotency_conflict.

Authentication with the inventory:write scope and Commerce request context is required.

Authorizations:
ApiKeyAuth
path Parameters
variantId
required
integer >= 1
Example: 51

Positive product variant identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

header Parameters
Idempotency-Key
required
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: inventory-request-501

Caller-generated identifier that makes one mutation safe to retry. Keys are scoped to the authenticated API client and must not be reused for different normalized request data.

Request Body schema: application/json
required
quantityDelta
required
number decimal places <= 4 [ -1000000000000000 .. 1000000000000000 ]

Signed amount added to the current physical on-hand stock.

reason
required
string [ 1 .. 35 ] characters ^[a-z][a-z0-9._-]{0,34}$

Technical reason key stored with the inventory movement.

reference
string <= 120 characters

Optional external reference such as an ERP transaction ID.

note
string <= 1000 characters

Optional human-readable audit note.

Responses

Request samples

Content type
application/json
{
  • "quantityDelta": 3,
  • "reason": "stock_count",
  • "reference": "COUNT-9",
  • "note": "Warehouse count correction"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Carts

Server-side cart and checkout operations

Create a cart

Creates a new empty cart in the resolved shop, language, and currency context and returns its opaque public token plus the authoritative cart representation. Every successful request creates a fresh cart; an existing customer cart is never resumed implicitly.

The optional customer context is validated against the resolved shop. Supplying companyId also requires a company membership that permits ordering. Cart pricing follows the selected customer or company's customer-group context and the canonical base-price fallback. An explicit priceListId query parameter is therefore not supported.

Authentication with the checkout:write scope is required. Numeric internal cart IDs are never exposed.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
optional
customerId
integer or null >= 1

Optional active non-guest customer linked to the resolved shop.

companyId
integer or null >= 1

Optional active company for which the selected customer may order.

guestEmail
string or null <email> <= 255 characters

Optional guest email; it cannot be combined with customerId.

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a cart

Returns the authoritative persisted state for the cart selected by its opaque public token. The lookup is constrained to the resolved shop; a token from another shop is indistinguishable from an unknown token.

This operation is side-effect free. It does not update cart activity, refresh stored line prices, or reserve inventory. It does project the current shipping, payment, adjustment, tax, and grand-total breakdown through the shared checkout domain. Use the explicit refresh mutation when stored line prices must first be recalculated.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted. A cart's stored language, currency, and pricing context cannot be overridden while reading it.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get the available checkout methods for a cart

Resolves the shipping and payment methods that are currently available for the cart's persisted shop, customer, currency, items, addresses, and checkout selection. Shipping options contain the authoritative zone/rate result. Payment options contain the authoritative fee or discount that would apply to that method.

Method IDs in this response are the public global IDs accepted by the shipping-method and payment-method mutation endpoints. Internal shop assignment and rate IDs are not exposed. The cart's stored language, currency, and pricing context cannot be overridden.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Refresh cart pricing and checkout eligibility

Explicitly reprices every cart line from the cart's persisted customer, currency, price-list, and shop context, then reevaluates the checkout options, codes, adjustments, taxes, and eligibility through the shared checkout domain. The returned cart is the newly persisted authoritative state. Use the checkout-options operation to retrieve the refreshed method availability and resolved rates.

This endpoint accepts no request body. It exists so external channels can deliberately refresh a long-lived cart before displaying totals or submitting it instead of relying on side effects of a GET request.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Add an item to a cart

Adds a positive quantity of one shop-assigned active product or variant to an active cart and returns the complete authoritative cart representation. A product with active variants requires a concrete variantId. The quantity is the amount to add. When the same unconfigured product or variant line already exists, its quantity is incremented instead of creating a duplicate line.

The cart's stored customer, language, currency, price-list, and amount type context remains authoritative. The mutation validates the added line's minimum order quantity and inventory, resolves its price, and refreshes all cart line prices and the subtotal through the existing cart domain service. Clients must not calculate prices or totals.

The optional configuration object contains raw customer input keyed by the public technical field key. NetSeller passes those values through the registered core and plugin configuration contributors; only their validated, server-built snapshot, display data, line key, and pricing contribution are persisted. Clients cannot submit stored snapshots or trusted pricing metadata directly.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
productId
required
integer >= 1

Product assigned to the cart's resolved shop.

variantId
integer or null >= 1

Active variant belonging to productId; required when the product has active variants.

quantity
number decimal places <= 4 ( 0 .. 99999999.9999 ]
Default: 1

Positive amount to add to the existing cart line quantity.

object <= 100 properties

Raw line-item input keyed by technical field key, for example engraving_text. Values are validated by the registered line-item configuration contributors before a trusted snapshot is persisted.

Responses

Request samples

Content type
application/json
Example
{
  • "productId": 42,
  • "quantity": 2
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a cart item quantity

Replaces the absolute quantity of one existing line in an active cart and returns the complete authoritative cart representation. This is not an increment operation. A quantity of zero does not remove the line; clients use the separate DELETE operation for removal.

The line keeps its product, variant, and trusted configuration snapshot. The mutation validates minimum order quantity and inventory, resolves the line price from the cart's stored pricing context, and refreshes all cart line prices and the subtotal through the existing cart domain service. Clients must not calculate prices or totals.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary. An item belonging to another cart is indistinguishable from an unknown item.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

itemId
required
integer >= 1
Example: 501

Positive identifier of an existing line in the selected cart.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
quantity
required
number decimal places <= 4 ( 0 .. 99999999.9999 ]

New absolute line quantity; use DELETE to remove the item.

Responses

Request samples

Content type
application/json
{
  • "quantity": 4.5
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Remove an item from a cart

Removes one existing line from an active cart and returns the complete authoritative cart representation. The cart domain refreshes the remaining line prices and subtotal. Clients must use the returned cart instead of calculating totals locally.

Authentication with the checkout:write scope is required. The request has no body and accepts only the optional shopId commerce parameter. It must resolve to the cart's authorized shop boundary. An item belonging to another cart is indistinguishable from an unknown item. Repeating a successful removal therefore returns cart_item_not_found.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

itemId
required
integer >= 1
Example: 501

Positive identifier of an existing line in the selected cart.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Create or replace a cart address

Creates or replaces the cart's billing or shipping address snapshot and returns the complete authoritative cart representation. Billing and shipping addresses are independent; this operation does not copy one role to the other.

Only manual address fields are accepted. Internal source types and stored customer or company address references cannot be supplied. The country, salutation, and optional title are validated against active master data using the cart's stored language context. A country may be identified by countryId or countryIsoCode; when both are supplied, they must refer to the same country.

customFields contains raw values keyed by technical field key. Only active, storefront-editable definitions assigned to the selected shop, person/company address type, and billing/shipping role are accepted. Required and typed values follow the existing storefront checkout rules.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary. Only active carts can be changed.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

addressRole
required
string
Enum: "billing" "shipping"
Example: billing

Checkout address role to create or replace.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
Any of
countryId
required
integer >= 1

Active country; either this field or countryIsoCode is required.

salutationId
required
integer >= 1

Active salutation resolved in the cart's stored language.

titleId
integer or null >= 1

Optional active title.

company
string or null <= 255 characters
companyAddition
string or null <= 255 characters
firstName
required
string [ 1 .. 120 ] characters
lastName
required
string [ 1 .. 120 ] characters
street
required
string [ 1 .. 255 ] characters
streetNumber
string or null <= 40 characters
addressLine2
string or null <= 255 characters
postcode
required
string [ 1 .. 40 ] characters
city
required
string [ 1 .. 120 ] characters
state
string or null <= 120 characters
countryIsoCode
string^[A-Za-z]{2}$

Two-letter ISO country code; normalized to uppercase.

phone
string or null <= 80 characters
mobile
string or null <= 80 characters
object <= 100 properties

Raw storefront-editable address custom-field values keyed by technical field key.

Responses

Request samples

Content type
application/json
{
  • "salutationId": 1,
  • "firstName": "Regula",
  • "lastName": "Muster",
  • "street": "Marktgasse",
  • "streetNumber": "1",
  • "postcode": "3000",
  • "city": "Bern",
  • "countryIsoCode": "CH",
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Remove a cart address

Removes the cart's billing or shipping address snapshot and returns the complete authoritative cart representation. The two roles are independent, so deleting one does not modify the other. Custom-field values belonging to the deleted role are removed atomically with the address.

The operation is idempotent. When the selected address is already absent, the unchanged authoritative cart is returned successfully. The request has no body.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary. Only active carts can be changed.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

addressRole
required
string
Enum: "billing" "shipping"
Example: billing

Checkout address role to create or replace.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Select a cart shipping method

Selects a shipping method and returns the complete authoritative cart representation. shippingMethodId is the public global method ID returned by /shops/{shopId}/shipping-methods; the server resolves it to the active assignment of the cart's shop.

Availability is evaluated by the existing checkout domain. The method must have an active rate for the cart currency and destination, using the shipping address or falling back to the billing address. Cart subtotal, weight, pickup-only products, and required checkout address custom fields are also respected. Internal shop-assignment IDs cannot be supplied or discovered through this endpoint.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary. Only active carts can be changed.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
shippingMethodId
required
integer >= 1

Public global ID returned by the selected shop's shipping-method collection.

Responses

Request samples

Content type
application/json
{
  • "shippingMethodId": 4
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Select a cart payment method

Selects a payment method and returns the complete authoritative cart representation. paymentMethodId is the public global method ID returned by /shops/{shopId}/payment-methods. Payment methods are global master data with explicit shop assignments; internal assignment IDs cannot be supplied or discovered through this endpoint.

A valid shipping method must be available. When exactly one shipping option exists, the existing checkout behavior may select it automatically. Availability is evaluated by the existing checkout domain, including the active shop assignment, shipping-method restrictions, customer or company rules, minimum paid-order requirements, and payment-method adjustments.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary. Only active carts can be changed.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
paymentMethodId
required
integer >= 1

Public global ID returned by the selected shop's payment-method collection.

Responses

Request samples

Content type
application/json
{
  • "paymentMethodId": 6
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Apply a coupon or voucher code to a cart

Submits one checkout code and returns the complete authoritative cart representation. The existing checkout domain determines whether the code is a coupon or voucher and validates its shop, customer, currency, validity, usage, balance, calculation basis, and combinability.

The current checkout domain permits one active discount code effect, so an eligible code replaces the existing coupon or voucher selection. Voucher balance and coupon usage are consumed only during successful order submission. A rejected request restores the previous code selection and uses a generic error that does not reveal whether the submitted code exists.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary. Only active carts can be changed.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
code
required
string [ 1 .. 120 ] characters

One coupon or voucher code; comma-separated or multiline lists are not accepted.

Responses

Request samples

Content type
application/json
{
  • "code": "WELCOME10"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Remove a coupon or voucher code from a cart

Removes the matching selected checkout code and returns the complete recalculated authoritative cart representation. Coupon usage and voucher balance are not consumed or changed by this operation.

Code matching is case-insensitive. If the code is not currently selected, the operation returns checkout_code_not_found; repeating a successful removal therefore leaves the same cart state but returns a not-found response.

Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted; it must resolve to the cart's authorized shop boundary. Only active carts can be changed.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

code
required
string [ 1 .. 120 ] characters
Example: WELCOME10

Selected coupon or voucher code, encoded as one URL path segment.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Submit a cart and create its order

Revalidates and submits the authoritative cart selected by its opaque token. The cart's stored shop, customer or company context, addresses, shipping method, payment method, prices, totals, coupon codes, and voucher codes are used as-is; clients cannot override or calculate these values in the submission request.

For an internal payment method, a successful request creates the order immediately and returns its complete public representation with 201. Repeating submission after that order was created is idempotent and returns the same order with 200. For an external redirect payment, the response uses 202 and contains the provider redirect URL plus an opaque payment-session key. Provider return and notification URLs are generated by the server and cannot be supplied by the client. Repeating the request while that payment is pending returns the same redirect URL and session key without initializing another provider payment. After a successful provider callback, repeating the request returns the created order with 200; clients therefore use this same operation to continue the public flow idempotently.

customFields accepts storefront-editable order custom-field values by their technical keys. The existing checkout domain validates required fields and persists accepted values with the order. Authentication with the checkout:write scope is required. Only the optional shopId commerce parameter is accepted and must match the cart's shop boundary.

Authorizations:
ApiKeyAuth
path Parameters
cartToken
required
string [ 1 .. 255 ] characters
Example: 5f90a78d66144eeaa3fe4d3fb6736f80

Opaque, unguessable public cart identifier returned when the cart is created.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
termsAccepted
required
boolean

Explicit confirmation that the checkout terms and conditions were accepted.

Value: true
orderReference
string <= 255 characters

Optional customer-facing order reference.

customerNote
string <= 65535 characters

Optional note stored with the order.

object <= 100 properties

Storefront-editable order custom-field values keyed by technical field key.

Responses

Request samples

Content type
application/json
{
  • "termsAccepted": true,
  • "orderReference": "WEB-2026-1842",
  • "customerNote": "Please leave the parcel at reception.",
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Orders

Shop-isolated order reads and controlled operations over persisted historical snapshots

Get the order status catalog

Returns the complete canonical technical keys for order, payment, and fulfillment statuses. The catalog is global metadata and does not require Commerce shop context.

Authentication with the orders:read scope is required.

The response does not describe allowed transitions for a concrete order. A listed status is therefore not necessarily a valid next status from every current order state.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List orders

Returns orders belonging to the resolved shop. Every customer, currency, total, payment, and shipping value comes from the persisted order snapshots. Current customer, pricing, tax, shipping, payment, language, and currency configuration is never used to recalculate historical orders.

q performs a case-insensitive substring search across the order number, customer email, customer number, company name, company number, customer first and last names, the combined customer name, and customer reference. Status, sales-channel, customer, company, placement-time, and update-time filters are exact or exclusive as documented by their parameters.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

sort
string^-?(id|orderNumber|orderStatus|placedAt|total...
Default: "-placedAt"
Examples:
  • sort=updatedAt,id -

Comma-separated order summary fields. Supported fields are id, orderNumber, orderStatus, placedAt, totalGross, and updatedAt. Prefix a field with - for descending order. The order ID is added as the final deterministic tie-breaker when omitted.

q
string <= 200 characters
Examples:
  • q=100042 -

Case-insensitive substring search across order number, customer email, customer number, company name, company number, customer first and last names, the combined customer name, and customer reference.

orderStatus
string [ 1 .. 40 ] characters ^[a-z][a-z0-9_]*$
Examples:
  • orderStatus=open -

Exact technical order-status key.

paymentStatus
string [ 1 .. 40 ] characters ^[a-z][a-z0-9_]*$
Examples:
  • paymentStatus=paid -

Exact technical payment-status key stored on the order.

fulfillmentStatus
string [ 1 .. 40 ] characters ^[a-z][a-z0-9_]*$
Examples:
  • fulfillmentStatus=pending -

Exact technical fulfillment-status key stored on the order.

salesChannel
string [ 1 .. 30 ] characters ^[a-z][a-z0-9_]*$
Examples:
  • salesChannel=storefront -

Exact technical sales-channel key stored on the order.

customerId
integer >= 1
Examples:
  • customerId=18 -

Restricts results to orders linked to this customer ID.

companyId
integer >= 1
Examples:
  • companyId=7 -

Restricts results to orders linked to this company ID.

placedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Examples:
  • placedAfter=2026-07-01T00:00:00Z -

Exclusive lower boundary for placedAt. Only orders with placedAt > placedAfter are returned.

placedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Examples:
  • placedBefore=2026-08-01T00:00:00Z -

Exclusive upper boundary for placedAt. Only orders with placedAt < placedBefore are returned. When both placement boundaries are present, this value must be later than placedAfter.

updatedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Examples:
  • updatedAfter=2026-07-01T00:00:00Z -

Exclusive lower boundary for the order's updatedAt. Only orders with updatedAt > updatedAfter are returned.

updatedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Examples:
  • updatedBefore=2026-08-01T00:00:00Z -

Exclusive upper boundary for the order's updatedAt. Only orders with updatedAt < updatedBefore are returned. When both update boundaries are present, this value must be later than updatedAfter.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get an order

Returns one historical order belonging to the resolved shop. The response contains the persisted order, customer, address, item, payment, shipping, and shipment snapshots. Current commerce master data is never used to recalculate or replace those values.

Billing and shipping addresses are separate role-specific snapshots. Their contents may therefore be identical while their role and id values remain distinct. Root order custom fields use the current connector-visible definitions, while address custom fields remain the immutable connector-visible snapshots captured with the order.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List order refunds

Returns persisted refund history for one order in the resolved shop. Refunded item values are historical snapshots. Generated voucher or coupon codes and internal admin actor data are never exposed.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create an order refund

Records a validated manual, voucher, or coupon refund through the shared refund domain for an order belonging to the resolved shop. Authentication with the orders:write scope is required.

Optional item entries identify historical order positions. Their amounts must add up to the refund amount, and the domain enforces the remaining refundable order amount, quantities, and item amounts. Immutable order snapshots and the order's shop ownership are not changed. Generated voucher or coupon credit codes are never exposed.

An optional Idempotency-Key makes retries safe. The same API client, key, and normalized request return the original refund with 200; reusing the key for different request data returns 409 idempotency_conflict.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

header Parameters
Idempotency-Key
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: order-mutation-501

Optional caller-generated identifier that makes one resource creation safe to retry. Keys are scoped to the authenticated API client and must not be reused for different normalized request data.

Request Body schema: application/json
required
method
required
string
Enum: "manual" "voucher" "coupon"
amount
required
number decimal places <= 4 ( 0 .. 999999999999.9999 ]
externalReference
string or null <= 190 characters
reason
string or null <= 5000 characters
Array of objects (OrderRefundCreateItemRequest) <= 100 items

Responses

Request samples

Content type
application/json
Example
{
  • "method": "manual",
  • "amount": 25,
  • "externalReference": "ERP-RMA-8821",
  • "reason": "Damaged item",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get an order refund

Returns one persisted refund belonging to the specified order and resolved shop.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

refundId
required
integer >= 1
Examples:
  • 91 -

Positive order-refund identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Void an order refund

Safely transitions a refund to voided while preserving its persisted refund and item snapshots. The order and refund must both belong to the resolved shop, and orders:write is required.

Voucher and coupon credits are voided only when they have not been redeemed. Unsafe state transitions return a conflict without changing the refund. Generated credit codes and internal actor data are never exposed.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

refundId
required
integer >= 1
Examples:
  • 91 -

Positive order-refund identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List order documents

Returns immutable document metadata for one historical order in the resolved shop. The order and every document are constrained to the selected shop. Internal filesystem paths, template snapshots, and rendering details are never exposed.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Generate an order document

Generates one policy-approved order document for an order in the resolved shop. The shared document domain selects the effective shop/language template, reserves the document number, snapshots the historical order and template, and renders the PDF.

Callers cannot supply a template, number, filename, language, or body. Credit notes must reference one active refund belonging to the same order and shop. Incomplete records and PDFs are removed when rendering or history recording fails.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
One of
type
required
string
Enum: "invoice" "delivery_note" "cancellation"

Responses

Request samples

Content type
application/json
Example
{
  • "type": "invoice"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Download an order document

Returns the PDF binary for a document belonging to the specified historical order in the resolved shop. The response is a file download, not the JSON API envelope. The PDF is rendered from immutable order and document-template snapshots.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

documentId
required
integer >= 1
Examples:
  • 151 -

Positive immutable order-document identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": null,
  • "meta": {
    },
  • "errors": [
    ]
}

Delete an undelivered order document

Deletes a document and its generated PDF only while no delivery has been recorded. Delivery history and document-linked communications make delivered documents immutable. The document must belong to the specified order and resolved shop.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

documentId
required
integer >= 1
Examples:
  • 151 -

Positive immutable order-document identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Send an order document

Sends the existing PDF using only immutable and configured inputs. The recipient comes from the order snapshot, the language from the document, and the subject and body from the document-type-bound email template. This operation accepts no request body and exposes no recipient, subject, message, template, or attachment override.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

documentId
required
integer >= 1
Examples:
  • 151 -

Positive immutable order-document identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List order communication history

Returns the chronological public outbound communication history for an order in the resolved shop. Internal admin identifiers, usernames, actor labels, translation keys, and template configuration are omitted.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Send a bounded order communication

Sends one explicitly supported order communication through its fixed configured template. The recipient and language are taken from the immutable order snapshot. Callers cannot provide a recipient, language, subject, body, raw HTML, arbitrary template, or attachment.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
One of
type
required
string
Value: "order_confirmation"

Responses

Request samples

Content type
application/json
Example
{
  • "type": "order_confirmation"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Change one order status

Performs one allowed transition in the order, payment, or fulfillment status domain for an order belonging to the resolved shop.

Authentication with the orders:write scope and Commerce shop context is required. Missing and foreign-shop orders return the same 404 order_not_found response.

The shared order lifecycle applies its intrinsic reservation, inventory-booking, payment/shipping snapshot, and status-history effects. The authenticated API client is recorded as the actor. Notifications, documents, refunds, shipment creation, and tracking updates are not performed by this endpoint.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
One of
statusType
required
string
Value: "order"
nextStatus
required
string
Enum: "open" "completed" "cancelled"
note
string <= 5000 characters

Responses

Request samples

Content type
application/json
Example
{
  • "statusType": "payment",
  • "nextStatus": "paid",
  • "note": "Payment confirmed by ERP."
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List order shipments

Returns persisted shipment and tracking entries for one order in the resolved shop. The order is authorized before shipment data is read.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create an order shipment

Creates one persisted shipment tracking record for an order belonging to the resolved shop. This does not change lifecycle statuses, book inventory, call a carrier, generate a label, or send a notification. An optional Idempotency-Key returns the original shipment with 200 on a matching retry and rejects different request data with 409 idempotency_conflict.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

header Parameters
Idempotency-Key
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: order-mutation-501

Optional caller-generated identifier that makes one resource creation safe to retry. Keys are scoped to the authenticated API client and must not be reused for different normalized request data.

Request Body schema: application/json
required
trackingNumber
required
string [ 1 .. 190 ] characters
trackingUrl
string <uri> <= 500 characters
shippedAt
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

Optional RFC 3339 UTC timestamp; defaults to server time.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get an order shipment

Returns one persisted shipment constrained to the specified order and resolved shop.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

shipmentId
required
integer >= 1
Examples:
  • 92 -

Positive order-shipment identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete an order shipment

Deletes one shipment constrained to the specified order and resolved shop and returns its former public snapshot. Historical order, shipping, customer, address, price, and item snapshots are unchanged.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

shipmentId
required
integer >= 1
Examples:
  • 92 -

Positive order-shipment identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Create an order tracking entry

Creates one persisted shipment tracking record for an order belonging to the resolved shop. Authentication with the orders:write scope and Commerce shop context is required. Missing and foreign-shop orders return the same 404 order_not_found response.

This endpoint does not change an order, payment, or fulfillment status, book inventory, call a carrier, generate labels, or send notifications. Multiple tracking entries can be created for the same order. An optional Idempotency-Key returns the original entry with 200 on a matching retry and rejects different request data with 409 idempotency_conflict.

Authorizations:
ApiKeyAuth
path Parameters
orderId
required
integer >= 1
Examples:
  • 1042 -

Positive historical order identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

header Parameters
Idempotency-Key
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: order-mutation-501

Optional caller-generated identifier that makes one resource creation safe to retry. Keys are scoped to the authenticated API client and must not be reused for different normalized request data.

Request Body schema: application/json
required
trackingNumber
required
string [ 1 .. 190 ] characters
trackingUrl
string <uri> <= 500 characters
shippedAt
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

Optional RFC 3339 UTC timestamp; defaults to server time.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Customers

Shop-scoped, credential-free customer reads and controlled writes

List customer groups

Returns the global customer-group catalog in the resolved language. The selected shop authorizes and resolves the language context, but it does not filter the global groups. A customer group's optional price list is a global pricing reference, not a shop-specific override.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List salutations

Returns the global salutation master-data registry in the resolved language. The selected shop authorizes and resolves the language context, but does not filter the registry. Active state and sort order are included so integrations can retain stable customer references.

The response exposes the technical key and resolved display name only; it does not expose letter-salutation templates or raw translations.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List titles

Returns the global academic and honorific-title master-data registry in the resolved language. The selected shop authorizes and resolves the language context, but does not filter the registry. Active state and sort order are included so integrations can retain stable customer references.

The response exposes the technical key and resolved display name only; it does not expose raw translations or administrative configuration.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

priceListId
integer >= 1
Example: priceListId=4

Existing price list used for price resolution. When omitted, standard base-price resolution is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List customers

Returns customer accounts linked to the resolved shop. Customer identity is global, while the customer-shop link is the visibility boundary. Credentials, addresses, company memberships, customer groups, and other shop assignments are not included.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

sort
string^-?(id|number|email|lastName|createdAt|update...
Default: "id"
Example: sort=-updatedAt,id

Comma-separated customer fields. Supported fields are id, number, email, lastName, createdAt, and updatedAt. Prefix a field with - for descending order.

q
string <= 200 characters
Example: q=muster

Case-insensitive substring search across customer number, email, first name, and last name.

updatedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedAfter=2026-08-01T00:00:00Z

Exclusive lower boundary for customer updatedAt.

updatedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedBefore=2026-08-02T00:00:00Z

Exclusive upper boundary for customer updatedAt; it must be later than updatedAfter when both are supplied.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a customer identity

Creates a credential-free global customer identity and an active registration in the resolved shop. Passwords, reset data, payment credentials, and newsletter consent are not accepted.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
email
required
string <email> <= 255 characters
number
required
string [ 1 .. 255 ] characters
salutationId
integer or null >= 1
titleId
integer or null >= 1
firstName
string <= 120 characters
lastName
string <= 120 characters
active
boolean
Default: true
guest
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "number": "string",
  • "salutationId": 1,
  • "titleId": 1,
  • "firstName": "string",
  • "lastName": "string",
  • "active": true,
  • "guest": false
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a customer

Returns one private customer linked to the resolved shop, including the current shop assignment, customer group, connector-visible customer custom fields, and addresses. Credentials, company assignments, and other shop assignments are never exposed.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a customer identity

Partially updates the global identity of a customer linked to the resolved shop. Shop-registration fields use their dedicated contract.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
email
string <email> <= 255 characters
number
string [ 1 .. 255 ] characters
salutationId
integer or null >= 1
titleId
integer or null >= 1
firstName
string <= 120 characters
lastName
string <= 120 characters
active
boolean
guest
boolean

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "number": "string",
  • "salutationId": 1,
  • "titleId": 1,
  • "firstName": "string",
  • "lastName": "string",
  • "active": true,
  • "guest": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace connector-visible customer custom fields

Replaces the complete connector-visible custom-field value set for a customer registered in the resolved shop. Omitted connector-visible definitions are cleared; non-connector definitions are untouched.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
required
object <= 100 properties

Complete connector-visible value set keyed by custom-field key. Use null to clear a value; omitted connector-visible definitions are also cleared. Custom fields must not be used to store authentication secrets or sensitive payment credentials.

Responses

Request samples

Content type
application/json
{
  • "customFields": { }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get effective newsletter consent

Returns the effective selected-shop consent state and its latest explicit event. No state is inferred from customer identity or registration fields, and request evidence such as IP address or user agent is not exposed.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Record newsletter consent

Records an explicit selected-shop grant event. The operation is idempotent while the latest effective event is already granted.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
confirmed
required
boolean

Explicit affirmative confirmation for the grant or withdrawal represented by the endpoint.

Value: true
source
required
string [ 1 .. 80 ] characters ^[a-z][a-z0-9_.-]*$

Stable lower-case audit source key, for example erp_sync.

Responses

Request samples

Content type
application/json
{
  • "confirmed": true,
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Withdraw newsletter consent

Records an explicit selected-shop withdrawal event. The operation is idempotent while the latest event is already withdrawn.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
confirmed
required
boolean

Explicit affirmative confirmation for the grant or withdrawal represented by the endpoint.

Value: true
source
required
string [ 1 .. 80 ] characters ^[a-z][a-z0-9_.-]*$

Stable lower-case audit source key, for example erp_sync.

Responses

Request samples

Content type
application/json
{
  • "confirmed": true,
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a customer shop registration

Partially updates registration status, customer number, group, language, and currency in the resolved shop. The resulting pricing context is derived from the selected customer group and currency; arbitrary price-list assignment is not accepted.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
number
string or null <= 100 characters
status
string
Enum: "active" "inactive" "guest" "pending_verification" "pending_approval" "pending_verification_approval"
customerGroupId
integer or null >= 1
languageId
integer or null >= 1
currencyId
integer or null >= 1

Responses

Request samples

Content type
application/json
{
  • "number": "string",
  • "status": "active",
  • "customerGroupId": 1,
  • "languageId": 1,
  • "currencyId": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List customer shop registrations

Returns only customer registrations for active shops authorized for the API client.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Replace authorized customer shop registrations

Replaces the registration set within the API client's authorized shops while preserving registrations outside that boundary. The resolved shop registration must be retained.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
shopIds
required
Array of integers non-empty unique [ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "shopIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List customer addresses

Returns addresses available to one private customer through its link to the resolved shop. Company addresses and addresses belonging only to other customer-shop links are not exposed.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a customer address

Creates an address for a customer visible through the resolved shop registration. Default roles use the dedicated defaults operation.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
type
string <= 30 characters
label
string <= 120 characters
company
string <= 255 characters
salutationId
integer or null >= 1
titleId
integer or null >= 1
firstName
string <= 120 characters
lastName
string <= 120 characters
street
required
string <= 255 characters
streetNumber
string <= 40 characters
addressLine2
string <= 255 characters
postcode
required
string <= 40 characters
city
required
string <= 120 characters
state
string <= 120 characters
countryIsoCode
required
string^[A-Za-z]{2}$
phone
string <= 80 characters
mobile
string <= 80 characters
email
string <email> <= 255 characters
active
boolean

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "label": "string",
  • "company": "string",
  • "salutationId": 1,
  • "titleId": 1,
  • "firstName": "string",
  • "lastName": "string",
  • "street": "string",
  • "streetNumber": "string",
  • "addressLine2": "string",
  • "postcode": "string",
  • "city": "string",
  • "state": "string",
  • "countryIsoCode": "string",
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "active": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a customer address

Partially updates an address visible through the customer's resolved shop registration.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

addressId
required
integer >= 1
Example: 12

Stable customer-address identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
type
string <= 30 characters
label
string <= 120 characters
company
string <= 255 characters
salutationId
integer or null >= 1
titleId
integer or null >= 1
firstName
string <= 120 characters
lastName
string <= 120 characters
street
string <= 255 characters
streetNumber
string <= 40 characters
addressLine2
string <= 255 characters
postcode
string <= 40 characters
city
string <= 120 characters
state
string <= 120 characters
countryIsoCode
string^[A-Za-z]{2}$
phone
string <= 80 characters
mobile
string <= 80 characters
email
string <email> <= 255 characters
active
boolean

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "label": "string",
  • "company": "string",
  • "salutationId": 1,
  • "titleId": 1,
  • "firstName": "string",
  • "lastName": "string",
  • "street": "string",
  • "streetNumber": "string",
  • "addressLine2": "string",
  • "postcode": "string",
  • "city": "string",
  • "state": "string",
  • "countryIsoCode": "string",
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "active": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a customer address

Deletes an address visible through the customer's resolved shop registration.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

addressId
required
integer >= 1
Example: 12

Stable customer-address identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update customer address defaults

Atomically sets or clears the selected address as the customer's default billing or shipping address.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

addressId
required
integer >= 1
Example: 12

Stable customer-address identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
billing
boolean
shipping
boolean

Responses

Request samples

Content type
application/json
{
  • "billing": true,
  • "shipping": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace connector-visible customer-address custom fields

Replaces the complete connector-visible custom-field value set for an address visible through the customer's resolved-shop registration.

Authorizations:
ApiKeyAuth
path Parameters
customerId
required
integer >= 1
Example: 41

Positive global customer identifier linked to the resolved shop.

addressId
required
integer >= 1
Example: 12

Stable customer-address identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
required
object <= 100 properties

Complete connector-visible value set keyed by custom-field key. Use null to clear a value; omitted connector-visible definitions are also cleared. Custom fields must not be used to store authentication secrets or sensitive payment credentials.

Responses

Request samples

Content type
application/json
{
  • "customFields": { }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Companies

Shop-scoped, credential-free B2B company reads and controlled writes

List companies

Returns B2B companies assigned to the resolved shop. The company record is shared, while its explicit company-shop assignment is the visibility boundary. Company members, addresses, custom fields, and other shop assignments are not included.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

sort
string^-?(id|number|name|email|createdAt|updatedAt)...
Default: "id"
Example: sort=-updatedAt,id

Comma-separated company fields. Supported fields are id, number, name, email, createdAt, and updatedAt. Prefix a field with - for descending order.

q
string <= 200 characters
Example: q=muster

Case-insensitive substring search across company number, name, addition, VAT ID, and email.

updatedAfter
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedAfter=2026-08-01T00:00:00Z

Exclusive lower boundary for company updatedAt.

updatedBefore
string <date-time> ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: updatedBefore=2026-08-02T00:00:00Z

Exclusive upper boundary for company updatedAt; it must be later than updatedAfter when both are supplied.

shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a company

Creates global company master data and assigns the company to the resolved shop.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
name
required
string <= 255 characters
addition
string <= 255 characters
number
string <= 100 characters
vatId
string <= 100 characters
email
string <email> <= 255 characters
status
string
Enum: "active" "inactive"
active
boolean
customerGroupId
integer or null >= 1

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "addition": "string",
  • "number": "string",
  • "vatId": "string",
  • "email": "user@example.com",
  • "status": "active",
  • "active": true,
  • "customerGroupId": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a company

Returns one B2B company assigned to the resolved shop, including the selected shop, customer-group pricing context, connector-visible company custom fields, and addresses owned by the company. Company members and other shop assignments are not exposed. Credentials, reset data, and sensitive payment credentials are never part of this representation.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update company master data

Partially updates global master data for a company visible through the resolved shop assignment.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
name
string <= 255 characters
addition
string <= 255 characters
number
string <= 100 characters
vatId
string <= 100 characters
email
string <email> <= 255 characters
status
string
Enum: "active" "inactive"
active
boolean
customerGroupId
integer or null >= 1

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "addition": "string",
  • "number": "string",
  • "vatId": "string",
  • "email": "user@example.com",
  • "status": "active",
  • "active": true,
  • "customerGroupId": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace connector-visible company custom fields

Replaces the complete connector-visible custom-field value set for a company assigned to the resolved shop. Omitted connector-visible definitions are cleared; non-connector definitions are untouched.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
required
object <= 100 properties

Complete connector-visible value set keyed by custom-field key. Use null to clear a value; omitted connector-visible definitions are also cleared. Custom fields must not be used to store authentication secrets or sensitive payment credentials.

Responses

Request samples

Content type
application/json
{
  • "customFields": { }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a company address

Creates an address for a company assigned to the resolved shop.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
type
string <= 30 characters
label
string <= 120 characters
company
string <= 255 characters
salutationId
integer or null >= 1
titleId
integer or null >= 1
firstName
string <= 120 characters
lastName
string <= 120 characters
street
required
string <= 255 characters
streetNumber
string <= 40 characters
addressLine2
string <= 255 characters
postcode
required
string <= 40 characters
city
required
string <= 120 characters
state
string <= 120 characters
countryIsoCode
required
string^[A-Za-z]{2}$
phone
string <= 80 characters
mobile
string <= 80 characters
email
string <email> <= 255 characters
active
boolean

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "label": "string",
  • "company": "string",
  • "salutationId": 1,
  • "titleId": 1,
  • "firstName": "string",
  • "lastName": "string",
  • "street": "string",
  • "streetNumber": "string",
  • "addressLine2": "string",
  • "postcode": "string",
  • "city": "string",
  • "state": "string",
  • "countryIsoCode": "string",
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "active": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace a company address

Fully replaces the writable fields of a company address visible through the resolved shop.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

addressId
required
integer >= 1
Example: 22

Positive address identifier owned by the company.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
type
string <= 30 characters
label
string <= 120 characters
company
string <= 255 characters
salutationId
integer or null >= 1
titleId
integer or null >= 1
firstName
string <= 120 characters
lastName
string <= 120 characters
street
required
string <= 255 characters
streetNumber
string <= 40 characters
addressLine2
string <= 255 characters
postcode
required
string <= 40 characters
city
required
string <= 120 characters
state
string <= 120 characters
countryIsoCode
required
string^[A-Za-z]{2}$
phone
string <= 80 characters
mobile
string <= 80 characters
email
string <email> <= 255 characters
active
boolean

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "label": "string",
  • "company": "string",
  • "salutationId": 1,
  • "titleId": 1,
  • "firstName": "string",
  • "lastName": "string",
  • "street": "string",
  • "streetNumber": "string",
  • "addressLine2": "string",
  • "postcode": "string",
  • "city": "string",
  • "state": "string",
  • "countryIsoCode": "string",
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "active": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a company address

Deletes an address belonging to the selected company when it is visible through the resolved shop.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

addressId
required
integer >= 1
Example: 22

Positive address identifier owned by the company.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update company address defaults

Atomically sets or clears the selected address as the company's default billing or shipping address.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

addressId
required
integer >= 1
Example: 22

Positive address identifier owned by the company.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
billing
boolean
shipping
boolean

Responses

Request samples

Content type
application/json
{
  • "billing": true,
  • "shipping": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Replace connector-visible company-address custom fields

Replaces the complete connector-visible custom-field value set for a company address visible through the resolved shop.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

addressId
required
integer >= 1
Example: 22

Positive address identifier owned by the company.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
required
object <= 100 properties

Complete connector-visible value set keyed by custom-field key. Use null to clear a value; omitted connector-visible definitions are also cleared. Custom fields must not be used to store authentication secrets or sensitive payment credentials.

Responses

Request samples

Content type
application/json
{
  • "customFields": { }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List company members

Lists the global memberships of a company assigned to the resolved shop. Selected-shop registration context is included per customer when available.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Add a company member

Adds a customer registered in the resolved shop to the global company membership.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
customerId
required
integer >= 1
role
string [ 1 .. 60 ] characters
Default: "member"
primaryContact
boolean
Default: false
canOrder
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "customerId": 1,
  • "role": "member",
  • "primaryContact": false,
  • "canOrder": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a company member

Partially updates the role, primary-contact state, or ordering permission of a company member.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

memberId
required
integer >= 1
Example: 33

Positive company-membership identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
role
string [ 1 .. 60 ] characters
primaryContact
boolean
canOrder
boolean

Responses

Request samples

Content type
application/json
{
  • "role": "string",
  • "primaryContact": true,
  • "canOrder": true
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a company member

Removes the selected global membership from the company without deleting the customer identity.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

memberId
required
integer >= 1
Example: 33

Positive company-membership identifier.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List company shop assignments

Returns only assignments to active shops authorized for the API client.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Replace authorized company shop assignments

Replaces the assignment set within the API client's authorized shops while preserving assignments outside that boundary. The resolved and primary shop assignments must be retained.

Authorizations:
ApiKeyAuth
path Parameters
companyId
required
integer >= 1
Example: 51

Positive company identifier assigned to the resolved shop.

query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
shopIds
required
Array of integers non-empty unique [ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "shopIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Marketing

Shop-scoped promotion and merchandising management

List coupons

Lists only coupons whose adjustment rule is explicitly scoped to the resolved shop. Requires marketing:read.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

q
string <= 200 characters
Example: q=running shoe

Free-text search term. Search behavior is endpoint-specific.

status
string
Default: "all"
Enum: "all" "draft" "active" "paused" "archived"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a coupon

Creates a coupon and its checkout adjustment rule with an explicit scope for the resolved shop. The resolved currency is used for fixed amounts. Requires marketing:write.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
name
string [ 1 .. 190 ] characters
status
string
Enum: "draft" "active" "paused" "archived"
codeMode
string
Enum: "public" "generated"
amountMode
string
Enum: "fixed" "percentage"
amountValue
number > 0
minimumCartSubtotal
number >= 0
maxTotalRedemptions
integer >= 0
maxRedemptionsPerCustomer
integer >= 0
validFrom
string or null <date-time>
validTo
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "draft",
  • "codeMode": "public",
  • "amountMode": "fixed",
  • "amountValue": 1,
  • "minimumCartSubtotal": 0,
  • "maxTotalRedemptions": 0,
  • "maxRedemptionsPerCustomer": 0,
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a coupon

Requires marketing:read and exact resolved-shop scope.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a coupon

Partially updates the coupon and its shop-scoped adjustment rule. Activation requires at least one active code. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
name
string [ 1 .. 190 ] characters
status
string
Enum: "draft" "active" "paused" "archived"
codeMode
string
Enum: "public" "generated"
amountMode
string
Enum: "fixed" "percentage"
amountValue
number > 0
minimumCartSubtotal
number >= 0
maxTotalRedemptions
integer >= 0
maxRedemptionsPerCustomer
integer >= 0
validFrom
string or null <date-time>
validTo
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "draft",
  • "codeMode": "public",
  • "amountMode": "fixed",
  • "amountValue": 1,
  • "minimumCartSubtotal": 0,
  • "maxTotalRedemptions": 0,
  • "maxRedemptionsPerCustomer": 0,
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List coupon codes

Requires marketing:read and exact coupon shop scope.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

q
string <= 200 characters
Example: q=running shoe

Free-text search term. Search behavior is endpoint-specific.

status
string
Default: "all"
Enum: "all" "active" "disabled" "used"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a coupon code

Creates one unique code, optionally assigned to a customer registered in the resolved shop. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
code
required
string^[A-Za-z0-9_-]{1,120}$
status
string
Enum: "active" "disabled"
isTransferable
boolean
maxRedemptions
integer >= 0
customerId
integer or null >= 1

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "status": "active",
  • "isTransferable": true,
  • "maxRedemptions": 0,
  • "customerId": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a coupon code

Updates bounded code status, transferability, or usage limit fields. Code values and customer assignments use separate contracts. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
couponCodeId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
status
string
Enum: "active" "disabled"
isTransferable
boolean
maxRedemptions
integer >= 0

Responses

Request samples

Content type
application/json
{
  • "status": "active",
  • "isTransferable": true,
  • "maxRedemptions": 0
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Assign a coupon code to a customer

Replaces the code's customer assignment with a customer registered in the resolved shop. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
couponCodeId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
customerId
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "customerId": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Clear a coupon-code customer assignment

Requires marketing:write and exact coupon shop scope.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
couponCodeId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List coupon redemptions

Lists lifecycle-written redemption history. This resource is read-only; coupon application and redemption remain authoritative in checkout and order placement. Requires marketing:read.

Authorizations:
ApiKeyAuth
path Parameters
couponId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List vouchers

Lists vouchers explicitly assigned to the resolved shop. Customer profile data and internal notes are not exposed. Requires marketing:read.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

q
string <= 200 characters
Example: q=running shoe

Free-text search term. Search behavior is endpoint-specific.

status
string
Default: "all"
Enum: "all" "draft" "active" "paused" "archived"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a voucher

Creates a manual voucher, its initial credit, and its explicit resolved-shop assignment in one transaction. The resolved currency is immutable for the voucher. Requires marketing:write.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
code
required
string^[A-Za-z0-9_-]{1,120}$
status
string
Default: "draft"
Enum: "draft" "active" "paused" "archived"
initialAmount
required
number decimal places <= 4 > 0
isTransferable
boolean
Default: true
customerId
integer >= 1

Optional registered customer in the resolved shop.

validFrom
string

ISO-compatible date-time, or an empty string for no lower bound.

validTo
string

ISO-compatible date-time, or an empty string for no upper bound.

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "status": "draft",
  • "initialAmount": 1,
  • "isTransferable": true,
  • "customerId": 1,
  • "validFrom": "string",
  • "validTo": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a voucher

Requires marketing:read and exact resolved-shop assignment.

Authorizations:
ApiKeyAuth
path Parameters
voucherId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update voucher configuration

Updates bounded lifecycle, transferability, and validity fields. Code, currency, initial amount, and remaining balance are immutable here; balance changes use the movement endpoint. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
voucherId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
status
string
Enum: "draft" "active" "paused" "archived"
isTransferable
boolean
validFrom
string

ISO-compatible date-time, or an empty string to clear the bound.

validTo
string

ISO-compatible date-time, or an empty string to clear the bound.

Responses

Request samples

Content type
application/json
{
  • "status": "draft",
  • "isTransferable": true,
  • "validFrom": "string",
  • "validTo": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Assign a voucher to a customer

Replaces the customer assignment with a registered customer in the resolved shop and makes the voucher non-transferable. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
voucherId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
customerId
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "customerId": 1
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Clear a voucher customer assignment

Clears the assignment and restores transferability. Requires marketing:write and exact resolved-shop assignment.

Authorizations:
ApiKeyAuth
path Parameters
voucherId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List voucher balance movements

Requires marketing:read and exact resolved-shop assignment.

Authorizations:
ApiKeyAuth
path Parameters
voucherId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Credit or debit a voucher balance

Applies a transaction-safe credit or debit. Idempotency is isolated per API client; replaying the same key and body returns the original movement, while reusing a key for a different request returns 409. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
voucherId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

header Parameters
Idempotency-Key
required
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: inventory-request-501

Caller-generated identifier that makes one mutation safe to retry. Keys are scoped to the authenticated API client and must not be reused for different normalized request data.

Request Body schema: application/json
required
type
required
string
Enum: "credit" "debit"
amount
required
number decimal places <= 4 > 0
note
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "type": "credit",
  • "amount": 1,
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List voucher redemptions

Lists lifecycle-written redemption history. This resource is read-only; voucher application and redemption remain authoritative in checkout and order placement. Requires marketing:read.

Authorizations:
ApiKeyAuth
path Parameters
voucherId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List price actions

Lists price actions targeted only to the resolved shop. Global and multi-shop actions are outside this API contract. Requires marketing:read.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

q
string <= 200 characters
Example: q=running shoe

Free-text search term. Search behavior is endpoint-specific.

status
string
Default: "all"
Enum: "all" "draft" "active" "paused" "archived"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a price action

Creates an action targeted only to the resolved shop. Empty product, category, and manufacturer target arrays mean all matching products in that shop. Fixed reductions use the resolved currency. Requires marketing:write.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
name
string [ 1 .. 190 ] characters
status
string
Enum: "draft" "active" "paused" "archived"
productStatusFilter
string
Enum: "all" "active" "inactive"
priceChangeType
string
Enum: "percentage_reduction" "fixed_reduction"
changeValue
number > 0
validFrom
string or null <date-time>
validTo
string or null <date-time>
priority
integer >= 0
shopIds
Array of integers = 1 items [ items >= 1 ]

If supplied, must contain only the resolved shop ID.

productIds
Array of integers unique [ items >= 1 ]
categoryIds
Array of integers unique [ items >= 1 ]
manufacturerIds
Array of integers unique [ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "draft",
  • "productStatusFilter": "all",
  • "priceChangeType": "percentage_reduction",
  • "changeValue": 1,
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "priority": 0,
  • "shopIds": [
    ],
  • "productIds": [
    ],
  • "categoryIds": [
    ],
  • "manufacturerIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a price action

Requires marketing:read and exact resolved-shop scope.

Authorizations:
ApiKeyAuth
path Parameters
priceActionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a price action

Partially updates configuration, schedule, and catalog targets while retaining exact resolved-shop scope. Requires marketing:write.

Authorizations:
ApiKeyAuth
path Parameters
priceActionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

currency
string^[A-Za-z]{3}$
Example: currency=CHF

Case-insensitive ISO 4217 code of an active currency. When omitted, the selected shop's configured default currency is used.

Request Body schema: application/json
required
name
string [ 1 .. 190 ] characters
status
string
Enum: "draft" "active" "paused" "archived"
productStatusFilter
string
Enum: "all" "active" "inactive"
priceChangeType
string
Enum: "percentage_reduction" "fixed_reduction"
changeValue
number > 0
validFrom
string or null <date-time>
validTo
string or null <date-time>
priority
integer >= 0
shopIds
Array of integers = 1 items [ items >= 1 ]

If supplied, must contain only the resolved shop ID.

productIds
Array of integers unique [ items >= 1 ]
categoryIds
Array of integers unique [ items >= 1 ]
manufacturerIds
Array of integers unique [ items >= 1 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "draft",
  • "productStatusFilter": "all",
  • "priceChangeType": "percentage_reduction",
  • "changeValue": 1,
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "priority": 0,
  • "shopIds": [
    ],
  • "productIds": [
    ],
  • "categoryIds": [
    ],
  • "manufacturerIds": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List action-price results

Lists stored action-price calculation results for the resolved shop. This resource is read-only; price actions are applied dynamically by the pricing resolver and do not overwrite base prices. Requires marketing:read.

Authorizations:
ApiKeyAuth
path Parameters
priceActionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List abandoned carts

Lists active, non-submitted carts with items whose last activity is older than the requested inactivity window and which have not produced an order. Results are restricted to the resolved shop and omit cart tokens, contact details, addresses, and checkout codes. Requires marketing:read.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

checkoutState
string
Default: "all"
Enum: "all" "cart" "customer" "addresses" "shipping" "payment" "review"
inactiveForSeconds
integer [ 300 .. 2592000 ]
Default: 1800

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get an abandoned cart

Returns the privacy-bounded cart summary and item snapshots only when the cart belongs to the resolved shop and satisfies the abandoned-cart definition. Requires marketing:read.

Authorizations:
ApiKeyAuth
path Parameters
cartId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

inactiveForSeconds
integer [ 300 .. 2592000 ]
Default: 1800

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Shops

Discovery of shops assigned to the API client

List assigned shops

Returns the active shops explicitly assigned to the authenticated API client. This discovery operation requires the settings:read scope but does not resolve a Commerce request context, so it never requires a shopId parameter. Inactive and unassigned shops are omitted.

Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=2

One-based page number.

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=50

Number of items returned per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get an assigned shop

Returns presentation-safe metadata for one active shop explicitly assigned to the authenticated API client. The operation requires settings:read but does not resolve a Commerce request context. Missing, inactive, and unassigned shop IDs all return the same 404 shop_not_found response.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List storefront languages for an assigned shop

Returns the complete active storefront-language registry after the requested active shop has been verified as assigned to the API client. Storefront languages are global master data; the selected shop only determines which language is marked default. The operation requires settings:read, does not resolve a Commerce request context, and accepts no query parameters.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List currencies for an assigned shop

Returns the complete active currency registry after the requested active shop has been verified as assigned to the API client. Currencies are global master data; the selected shop only determines which currency is marked default. globalDefault remains the global currency setting. The operation requires settings:read, does not resolve a Commerce request context, and accepts no query parameters.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List countries for an assigned shop

Returns the complete active country registry after the requested active shop has been verified as assigned to the API client. Countries are global master data; the selected shop supplies the preferred language for country names unless an active storefront language is requested. Names fall back to the global default language and then the base country name. The operation requires settings:read, does not resolve a Commerce request context, and accepts only the language query parameter.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List shipping zones for an assigned shop

Returns the active global shipping-zone registry and every assigned country after the requested active shop has been verified as assigned to the API client. The shop authorizes the request and resolves the language context; it does not filter the global zone registry. Names, descriptions, and country names resolve through an explicitly requested active storefront language, or the shop default language when omitted, then the global default language, and finally the base value. The operation requires settings:read, does not resolve a Commerce request context, and accepts only the language query parameter. It does not expose shipping-method assignments, cost rules, rates, currencies, or checkout availability.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List shipping methods for an assigned shop

Returns the active shipping methods explicitly assigned to the requested active shop after it has been verified as assigned to the API client. Results use the selected shop assignment order. Names, descriptions, and delivery-time names resolve through an explicitly requested active storefront language, or the shop default language when omitted, then the global default language, and finally the base value. The operation requires settings:read, does not resolve a Commerce request context, and accepts only the language query parameter. It does not calculate shipping rates, zones, or checkout availability.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List payment methods for an assigned shop

Returns the active payment methods explicitly assigned to the requested active shop after it has been verified as assigned to the API client. Results use the selected shop assignment order. Names and descriptions resolve through an explicitly requested active storefront language, or the shop default language when omitted, then the global default language, and finally the base value. The operation requires settings:read, does not resolve a Commerce request context, and accepts only the language query parameter. It does not calculate fees, payment eligibility, or checkout availability.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get public settings for an assigned shop

Returns stable, non-sensitive configuration for one active shop explicitly assigned to the authenticated API client: default language, currency, and timezone; the effective price-format locale; and SEO and sitemap flags. The operation requires settings:read, does not resolve a Commerce request context, and accepts no query parameters. It never exposes credentials, mail configuration, or shop profile data. Missing, inactive, and unassigned shop IDs all return 404 shop_not_found.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get tax settings for an assigned shop

Returns the active tax-rate registry after the requested active shop has been verified as assigned to the authenticated API client. Tax rates are global master data in the current model; the path shop is an access boundary and does not create a shop-specific tax override. Names use the requested active storefront language, or the global default language when omitted. The operation requires settings:read, does not resolve a Commerce request context, and does not calculate product, shipping, or destination-specific taxes.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get resolved theme settings for an assigned shop

Returns the declared, resolved presentation settings of the active storefront theme after the requested active shop has been verified as assigned to the authenticated API client. Each setting provides its manifest key, type, effective value, and default value. The operation requires settings:read, does not resolve a Commerce request context, and accepts no query parameters. It does not expose theme templates, asset URLs, manifest internals, or commerce behavior.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get effective registration rules for an assigned shop

Returns the effective public account and checkout registration policy after the requested active shop has been verified as assigned to the authenticated API client. A shop without its own policy inherits the default-shop policy and reports that fallback explicitly. The operation requires settings:read, accepts no query parameters, and never exposes credential compatibility flags or internal configuration identifiers.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List connector-visible custom-field definitions

Returns active custom-field definitions enabled for connector use in an assigned active shop. Labels, descriptions, and option labels use the requested active storefront language, or the shop default language when omitted, then the global default language. Inactive definitions and definitions not marked connector-visible are excluded. Options retain their active state so integrations can interpret historical values without treating inactive options as valid new selections. The response omits configured default values and internal row identifiers.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

entityType
required
string
Enum: "product" "product_variant" "category" "customer" "customer_address" "customer_company" "customer_company_address" "customer_order" "manufacturer"

Custom-field entity contract used by the public API.

query Parameters
language
string non-empty
Example: language=de

Case-insensitive ISO code of an active storefront language. When omitted, the selected shop's configured default language is used.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Settings

Public settings discovery and explicit master-data management boundaries

List public settings and master-data capabilities

Returns the explicit public management decision for each supported settings and master-data resource, including public operations, operation-specific scopes, representative endpoints, and rationale. This global capability registry requires settings:read; it describes API contracts but does not grant the caller any of their scopes. Price lists are the only externally managed registry in this set. All other registries are read-only or expose resolved checkout results only.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Webhooks

Shop-scoped outbound event subscriptions, delivery history, and replay

List supported webhook event types

Requires webhooks:read and a resolved shop context.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

List webhook subscriptions

Returns only subscriptions owned by the API client in the exact resolved shop. Requires webhooks:read.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Create a webhook subscription

Creates an HTTPS-only subscription in the resolved shop. The signing secret is returned exactly once. Requires webhooks:write.

Authorizations:
ApiKeyAuth
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
name
required
string [ 1 .. 190 ] characters
endpointUrl
required
string <uri> <= 2048 characters ^https://
status
string
Default: "active"
Enum: "active" "paused"
eventTypes
required
Array of strings non-empty unique
timeoutSeconds
integer [ 1 .. 30 ]
Default: 10
maxAttempts
integer [ 1 .. 12 ]
Default: 8
initialBackoffSeconds
integer [ 10 .. 3600 ]
Default: 60

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "endpointUrl": "http://example.com",
  • "status": "active",
  • "eventTypes": [
    ],
  • "timeoutSeconds": 10,
  • "maxAttempts": 8,
  • "initialBackoffSeconds": 60
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Get a webhook subscription

Returns an owned subscription in the exact resolved shop without exposing its signing secret. Requires webhooks:read.

Authorizations:
ApiKeyAuth
path Parameters
subscriptionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Update a webhook subscription

Replaces only supplied fields. Event-type replacement is atomic. Requires webhooks:write.

Authorizations:
ApiKeyAuth
path Parameters
subscriptionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 190 ] characters
endpointUrl
string <uri> <= 2048 characters ^https://
status
string
Enum: "active" "paused"
eventTypes
Array of strings non-empty unique
timeoutSeconds
integer [ 1 .. 30 ]
maxAttempts
integer [ 1 .. 12 ]
initialBackoffSeconds
integer [ 10 .. 3600 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "endpointUrl": "http://example.com",
  • "status": "active",
  • "eventTypes": [
    ],
  • "timeoutSeconds": 1,
  • "maxAttempts": 1,
  • "initialBackoffSeconds": 10
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Delete a webhook subscription

Deletes the subscription and its delivery history. Requires webhooks:write.

Authorizations:
ApiKeyAuth
path Parameters
subscriptionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Rotate a webhook signing secret

Invalidates the old secret and returns the replacement exactly once. Requires webhooks:write.

Authorizations:
ApiKeyAuth
path Parameters
subscriptionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

List recent webhook deliveries

Returns up to 100 recent deliveries for the owned subscription. Requires webhooks:read.

Authorizations:
ApiKeyAuth
path Parameters
subscriptionId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "errors": [ ]
}

Get a webhook delivery and its attempts

Returns one delivery and its attempt history for an owned subscription in the resolved shop. Requires webhooks:read.

Authorizations:
ApiKeyAuth
path Parameters
subscriptionId
required
integer >= 1
deliveryId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}

Queue a webhook delivery for replay

Requeues the original immutable event. Idempotency-Key is mandatory; the same key and delivery return the prior result. Requires webhooks:write.

Authorizations:
ApiKeyAuth
path Parameters
subscriptionId
required
integer >= 1
deliveryId
required
integer >= 1
query Parameters
shopId
integer >= 1
Example: shopId=2

Active shop used for the commerce request. The shop must be assigned to the authenticated API client. This parameter is required when the client has access to multiple active shops. When exactly one assigned shop is active, omitting the parameter selects that shop.

header Parameters
Idempotency-Key
required
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,189}$
Example: inventory-request-501

Caller-generated identifier that makes one mutation safe to retry. Keys are scoped to the authenticated API client and must not be reused for different normalized request data.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    },
  • "errors": [ ]
}