NetSeller – Swiss E-Commerce Solution Commerce API
API docs by Redocly

NetSeller Commerce API (1.0.0)

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.

Getting started

Follow this quick start to make the first successful request against a NetSeller installation.

1. Identify the API base URL

Each NetSeller installation exposes the versioned API below its own shop host:

https://shop.example.com/api/v1

api.netseller.net hosts this reference documentation only. It does not proxy requests to a shop installation.

2. Obtain an API key

Obtain a NetSeller API key from the operator of the target installation. The key is limited to explicitly assigned scopes and shops. Keep it in a server-side secret store and never expose it in storefront JavaScript or a public repository.

Send the key as a bearer token on every protected request:

Authorization: Bearer ns_api_...

3. Verify API availability

The status endpoint is public and confirms that API v1 is reachable:

export NETSELLER_API_BASE_URL="https://shop.example.com/api/v1"
export NETSELLER_API_KEY="ns_api_..."

curl -sS "${NETSELLER_API_BASE_URL}/status"

A successful response contains data.status: "ok" and the active API version.

4. Discover assigned shops

With the settings:read scope, list the active shops assigned to the API client:

curl -sS \
  -H "Authorization: Bearer ${NETSELLER_API_KEY}" \
  "${NETSELLER_API_BASE_URL}/shops?page=1&perPage=25"

Use a returned shop ID as the shopId query parameter on shop-scoped requests. When the client has exactly one active assigned shop, NetSeller selects it automatically if shopId is omitted.

5. Read the first catalog page

The following request requires catalog:read. Language and currency are optional and otherwise use the selected shop's defaults.

curl -sS \
  -H "Authorization: Bearer ${NETSELLER_API_KEY}" \
  "${NETSELLER_API_BASE_URL}/products?shopId=2&language=de&currency=CHF&page=1&perPage=25"

Understand responses

JSON responses use a shared envelope:

{
  "data": {},
  "meta": {
    "requestId": "2db8c9e2-2771-4bd9-b243-6201be741d05"
  },
  "errors": []
}

Collection metadata also contains pagination. Preserve the response's X-Request-ID header or meta.requestId when reporting a problem. A 401 response indicates a missing or invalid key, 403 indicates a missing scope or shop assignment, and 422 indicates invalid request input.

Next steps

  • Use the navigation or search to find a resource and its required scope.
  • Send Content-Type: application/json for JSON request bodies.
  • Supply Idempotency-Key when an operation supports or requires it; reuse the same key only when retrying the exact request.
  • For protected catalog updates, read the authoritative resource first, retain its ETag, and send that value in If-Match. A 412 response means the resource changed and must be read again before retrying.
  • Download the OpenAPI YAML from the page header for client generation or local tooling.

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": [ ]
}

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, bounded storefront content, presentation settings, and manual redirects are the explicit write exceptions; all other registries are read-only or expose resolved checkout results only.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Shops

Discovery and configuration 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": [ ]
}

Update allowlisted active-theme settings

Partially updates presentation settings declared by the assigned shop's active theme manifest. Only manifest-declared color and image keys are accepted. Credential-like keys, undeclared keys, theme files, and arbitrary configuration paths are rejected. Omitted settings retain their current values. Requires settings:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Request Body schema: application/json
required
required
object [ 1 .. 50 ] properties

Partial key/value map. Every key must be declared by the active theme manifest and use one of the public color or image types.

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

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": [ ]
}

Storefront content

Localized text pages, footer columns, branding, and scheduled homepage composition

List homepage versions for one shop and language

Returns a deterministic page of homepage versions for the assigned shop and required active storefront language. Sections are available from the detail operation. Requires content:read.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
required
string^[A-Za-z]{2,10}$
Example: language=de

Required active storefront language ISO code for homepage authoring.

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": [ ]
}

Create a homepage version

Creates a homepage version in the required active storefront language. Status and schedule are explicit; overlapping active schedules are returned as warnings and resolved deterministically. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
required
string^[A-Za-z]{2,10}$
Example: language=de

Required active storefront language ISO code for homepage authoring.

Request Body schema: application/json
required
name
required
string [ 1 .. 190 ] characters
status
string (HomepageLifecycleStatus)
Enum: "draft" "active" "paused" "archived"
audience
string
Default: "all"
Enum: "all" "guest" "signed_in"
validFrom
string or null <date-time>
validTo
string or null <date-time>
priority
integer [ 0 .. 100000 ]
Default: 100

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "draft",
  • "audience": "all",
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "priority": 100
}

Response samples

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

Get one homepage version and its ordered sections

Returns one homepage version belonging to the assigned shop, including all ordered authoring sections and current overlap warnings. Requires content:read.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

homepageVersionId
required
integer >= 1

Positive homepage-version identifier owned by the path shop.

Responses

Response samples

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

Update homepage version metadata and schedule

Partially updates the name, explicit lifecycle status, schedule, or priority of one shop-owned homepage version. Sections are replaced by their dedicated authoritative operation. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

homepageVersionId
required
integer >= 1

Positive homepage-version identifier owned by the path shop.

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 190 ] characters
status
string (HomepageLifecycleStatus)
Enum: "draft" "active" "paused" "archived"
audience
string
Enum: "all" "guest" "signed_in"
validFrom
string or null <date-time>
validTo
string or null <date-time>
priority
integer [ 0 .. 100000 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "draft",
  • "audience": "all",
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "priority": 0
}

Response samples

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

Replace ordered homepage sections

Authoritatively replaces all sections in submitted array order. Section payloads use a positive allowlist, and referenced catalog or media records must be available to the selected shop. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

homepageVersionId
required
integer >= 1

Positive homepage-version identifier owned by the path shop.

Request Body schema: application/json
required
required
Array of objects or objects or objects or objects or objects (HomepageSectionWrite) <= 50 items

Entire replacement; submitted array order becomes authoritative.

Responses

Request samples

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

Response samples

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

Copy a homepage version

Copies metadata and ordered sections into an assigned target shop and active target language. The copy always starts in draft state. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

homepageVersionId
required
integer >= 1

Positive homepage-version identifier owned by the path shop.

Request Body schema: application/json
required
targetShopId
required
integer >= 1
targetLanguage
required
string^[A-Za-z]{2,10}$
name
string [ 1 .. 190 ] characters

Responses

Request samples

Content type
application/json
{
  • "targetShopId": 1,
  • "targetLanguage": "string",
  • "name": "string"
}

Response samples

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

Archive a homepage version

Removes a shop-owned homepage version from active resolution by setting its explicit lifecycle state to archived. Historical authoring data is retained. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

homepageVersionId
required
integer >= 1

Positive homepage-version identifier owned by the path shop.

Responses

Response samples

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

Get a supported localized storefront text page

Returns one supported legal/storefront text page for an assigned active shop. language selects an active storefront language and defaults to the shop language. When that translation is missing or incomplete, the global default-language translation is returned and fallbackUsed is true. Inactive pages remain readable for authoring. Requires content:read; arbitrary translation tables and page keys are not exposed.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

pageKey
required
string
Enum: "imprint" "privacy_policy" "terms_conditions" "withdrawal_returns"
Example: privacy_policy

Supported storefront legal or information page key.

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": [ ]
}

Update a supported localized storefront text page

Partially updates one supported page in the explicitly selected language. Omitted language uses the shop default. Activating a page requires a non-empty title and body in that language; fallback content never makes an incomplete translation writable. Successful writes use the shared storefront text-page service and are immediately visible to storefront rendering. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

pageKey
required
string
Enum: "imprint" "privacy_policy" "terms_conditions" "withdrawal_returns"
Example: privacy_policy

Supported storefront legal or information page key.

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.

Request Body schema: application/json
required
non-empty
title
string <= 190 characters
bodyHtml
string <= 200000 characters
active
boolean

Responses

Request samples

Content type
application/json
{
  • "title": "Privacy policy",
  • "bodyHtml": "<p>How this shop processes personal data.</p>",
  • "active": true
}

Response samples

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

Get maintained localized footer content

Returns maintained footer content, including inactive columns and entries, for an assigned active shop and required active storefront language. Missing content returns maintained false and empty columns, without generated storefront fallback links. Requires content:read.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
required
string^[A-Za-z]{2,10}$

Active storefront language ISO code for footer authoring.

Responses

Response samples

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

Replace ordered localized footer columns

Authoritatively replaces all footer columns in submitted order, preserving footer intro and activation. Read first and preserve entries to retain. Supports at most five columns with eight link/text entries each. Empty columns removes all maintained columns. An initial replacement creates maintained content. Language is required; other shops and languages are unaffected. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

query Parameters
language
required
string^[A-Za-z]{2,10}$

Active storefront language ISO code for footer authoring.

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

Authoritative display order; an empty array clears all maintained columns.

Responses

Request samples

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

Response samples

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

Get presentation-safe storefront branding

Returns the assigned shop's allowlisted storefront identity, contact, social-link, and logo fields. Tax identifiers, legal registry data, addresses, credentials, provider configuration, and deployment settings are excluded. Requires content:read.

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": [ ]
}

Update allowlisted storefront branding

Partially updates presentation-safe profile fields for an assigned shop. logoMediaAssetId must reference a previewable media-library image; zero removes the current logo. Tax, legal-registry, postal-address, credential, provider, domain, and deployment fields are rejected. Requires content:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Request Body schema: application/json
required
non-empty
companyName
string [ 1 .. 255 ] characters
companyAddition
string <= 255 characters
contactPerson
string <= 255 characters
email
string <email> <= 255 characters
phone
string <= 100 characters
website
string <uri> <= 255 characters
facebookUrl
string <uri> <= 500 characters
instagramUrl
string <uri> <= 500 characters
linkedinUrl
string <uri> <= 500 characters
xUrl
string <uri> <= 500 characters
youtubeUrl
string <uri> <= 500 characters
tiktokUrl
string <uri> <= 500 characters
pinterestUrl
string <uri> <= 500 characters
logoMediaAssetId
integer >= 0

Positive image asset ID, or zero to remove the logo.

Responses

Request samples

Content type
application/json
{
  • "companyName": "NetSeller",
  • "email": "hello@example.com",
  • "website": "https://www.example.com",
  • "logoMediaAssetId": 31
}

Response samples

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

SEO redirects

Shop-scoped manual storefront redirect lifecycle

List manual SEO redirects

Returns a deterministic page of manual redirects for the assigned shop. Optional language and active-state filters do not expose canonical URL mappings or slug history. Requires settings:read.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

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.

language
string^([A-Za-z]{2,10}|global)$
Example: language=de

Active storefront language ISO code, or global for language-neutral redirects.

active
string
Enum: "true" "false"

Optional manual redirect active-state filter.

Responses

Response samples

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

Create a manual SEO redirect

Creates a shop-scoped manual 301 or 302 redirect. Relative storefront sources and targets are normalized; technical paths, duplicate sources, self redirects, and multi-hop loops are rejected. Requires settings:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

Request Body schema: application/json
required
language
string or null^[A-Za-z]{2,10}$
sourcePath
required
string <= 1024 characters ^/
targetUrl
required
string [ 1 .. 2048 ] characters
statusCode
integer
Default: 301
Enum: 301 302
active
boolean
Default: true
note
string <= 4000 characters

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "sourcePath": "string",
  • "targetUrl": "string",
  • "statusCode": 301,
  • "active": true,
  • "note": "string"
}

Response samples

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

Get one manual SEO redirect

Returns one manual redirect belonging to the assigned shop without exposing canonical mappings or slug history. Requires settings:read.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

redirectId
required
integer >= 1

Positive manual SEO redirect identifier owned by the path shop.

Responses

Response samples

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

Update a manual SEO redirect

Partially updates a shop-owned manual redirect and revalidates its source, target, language scope, duplicate key, and complete relative redirect chain. Requires settings:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

redirectId
required
integer >= 1

Positive manual SEO redirect identifier owned by the path shop.

Request Body schema: application/json
required
non-empty
language
string or null^[A-Za-z]{2,10}$
sourcePath
string <= 1024 characters ^/
targetUrl
string [ 1 .. 2048 ] characters
statusCode
integer
Enum: 301 302
active
boolean
note
string <= 4000 characters

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "sourcePath": "string",
  • "targetUrl": "string",
  • "statusCode": 301,
  • "active": true,
  • "note": "string"
}

Response samples

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

Deactivate a manual SEO redirect

Deactivates a shop-owned manual redirect while retaining its authoring and hit-count history. Canonical URL mappings and slug history are not modified. Requires settings:write.

Authorizations:
ApiKeyAuth
path Parameters
shopId
required
integer [ 1 .. 2147483647 ]
Examples:
  • 2 -

Positive shop identifier assigned to the API client.

redirectId
required
integer >= 1

Positive manual SEO redirect identifier owned by the path shop.

Responses

Response samples

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

Products

Product master-data 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.

sku
string [ 1 .. 255 ] characters
Example: sku=SKU-41

Exact product SKU/article-number filter. Unlike q, this parameter does not perform substring matching.

ean
string [ 1 .. 64 ] characters
Example: ean=7612345678901

Exact product EAN filter. Unlike q, this parameter does not perform substring matching.

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. Supply an optional Idempotency-Key to make exact retries safe for 24 hours.

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.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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, including inactive manufacturers. The assigned ID remains present in product and variant reads while the manufacturer is assigned to that 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. Unused authoring records may be removed through the guarded product DELETE operation. 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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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, including inactive manufacturers; zero clears it. The assigned ID remains present in product and variant reads while the manufacturer is assigned to that shop.

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": [ ]
}

Delete an unused product

Permanently deletes a product only while it is not assigned to another shop and neither it nor any of its variants has cart, order, inventory-movement, or inventory-reservation history. A shared or used product returns 409 product_in_use and must be deactivated with PATCH instead.

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.

Responses

Response samples

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

Product relationships

Product assignments, specifications, accessories, and recommendations

Get accessible product shop assignments

Returns the authoritative product assignment set within the authenticated API client's shop-access boundary. The product must be assigned to the resolved shop. Assignments to shops outside the client's access are intentionally omitted and remain preserved by replacement writes.

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": [ ]
}

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Get an ordered typed product relationship

Returns one directed relationship set from the source product to the visible target products in persisted order. Supported types are alternative, spare_part, consumable, and supported_set. Reverse edges are never implied. Targets outside the resolved shop are preserved but not disclosed; inactive visible targets are returned with active: false so clients can reconcile them.

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

Positive product identifier.

relationshipType
required
string
Enum: "alternative" "spare_part" "consumable" "supported_set"
Example: spare_part

Bounded directed product-relationship type.

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 an ordered typed product relationship

Replaces the ordered relationship targets visible in the resolved shop. Array order defines target order and an empty array clears the visible subset. Existing targets outside the shop boundary and their stored order remain unchanged. Duplicate IDs, self-references, unsupported types, and targets unavailable in the resolved shop are rejected deterministically. The operation is idempotent.

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

Positive product identifier.

relationshipType
required
string
Enum: "alternative" "spare_part" "consumable" "supported_set"
Example: spare_part

Bounded directed product-relationship type.

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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Complete desired ordered target set visible in the resolved shop. Hidden-shop targets and their persisted order are preserved.

Responses

Request samples

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

Response samples

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

List global accessory groups

Returns every global accessory group, including inactive groups, in deterministic sortOrder, localized with the requested language and configured fallback. Requires catalog: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.

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 global accessory group

Creates a global group and its name translation in the resolved language. The stable key is immutable. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires catalog: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.

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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
key
required
string^[a-z0-9][a-z0-9_-]{0,79}$
name
required
string [ 1 .. 120 ] characters

Name translation in the resolved request language.

sortOrder
integer [ 0 .. 2147483647 ]
Default: 0
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Get a global accessory group

Returns one global accessory group regardless of lifecycle state. The effective name uses the resolved language and fallback, while the translations array supports authoring reconciliation.

Authorizations:
ApiKeyAuth
path Parameters
accessoryGroupId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global accessory-group 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 or reactivate a global accessory group

Updates supplied fields only. name writes the resolved-language translation, sortOrder controls global ordering, and active: true reactivates a deactivated group. The stable key cannot be changed.

Authorizations:
ApiKeyAuth
path Parameters
accessoryGroupId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global accessory-group 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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Name translation in the resolved request language.

sortOrder
integer [ 0 .. 2147483647 ]
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Deactivate a global accessory group

Sets lifecycle state to inactive without deleting the group or any existing product assignments. Repeating the request is idempotent. Reactivate with PATCH and active: true.

Authorizations:
ApiKeyAuth
path Parameters
accessoryGroupId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global accessory-group 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 products contained in an accessory group

Returns the ordered accessory-group members assigned to the resolved shop. Members outside that shop are hidden from the response.

Authorizations:
ApiKeyAuth
path Parameters
accessoryGroupId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global accessory-group 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 products contained in an accessory group

Replaces the complete ordered member set visible in the resolved shop. Existing members outside that shop and their stored order are preserved. An empty array clears only the visible member set.

Authorizations:
ApiKeyAuth
path Parameters
accessoryGroupId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global accessory-group 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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Complete desired ordered member set visible in the resolved shop. Hidden-shop members and their persisted order are preserved.

Responses

Request samples

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

Response samples

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

Product media

Product and variant image-gallery management

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Media library

Global media assets, localized metadata, collections, and authorized usage inspection

List media-library assets

Searches the global media library with bounded pagination and returns metadata localized through the resolved commerce language. Storage disks and paths are never exposed. Requires media:read.

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.

q
string <= 200 characters
Example: q=running shoe

Free-text search term. Search behavior is endpoint-specific.

kind
string
Enum: "image" "document" "video" "audio" "archive"
Example: kind=image

Restricts media assets to one detected media kind.

collectionId
integer [ 1 .. 2147483647 ]
Example: collectionId=17

Restricts media assets to one global collection.

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": [ ]
}

Upload a media-library asset

Uploads one supported file, optionally writes metadata in the resolved language, and assigns existing media collections. The configured upload-size and MIME allowlists apply. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires media: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.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: multipart/form-data
required
file
required
string <binary>

One file accepted by the configured media MIME and size allowlists.

title
string <= 255 characters
altText
string <= 255 characters
description
string <= 10000 characters
active
boolean
Default: true
collectionIds
string^[0-9]+(,[0-9]+)*$

Optional comma-separated list of at most 100 distinct existing collection IDs.

Responses

Response samples

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

Import a remote media asset

Imports one public HTTP(S) resource with a 20-second timeout, five-redirect limit, 20 MB byte limit, and media MIME allowlist. Every redirect target is resolved and private, loopback, link-local, multicast, and reserved addresses are rejected. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires media: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.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
sourceUrl
required
string <uri> <= 2000 characters ^https?://
title
string <= 255 characters
altText
string <= 255 characters
description
string <= 10000 characters
active
boolean
Default: true
collectionIds
Array of integers <= 100 items unique [ items [ 1 .. 2147483647 ] ]

Responses

Request samples

Content type
application/json
{
  • "sourceUrl": "http://example.com",
  • "title": "string",
  • "altText": "string",
  • "description": "string",
  • "active": true,
  • "collectionIds": [
    ]
}

Response samples

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

Get a media asset

Returns one global media asset with metadata localized through the resolved language and without internal storage coordinates. Requires media:read.

Authorizations:
ApiKeyAuth
path Parameters
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.

Responses

Response samples

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

Update media metadata or lifecycle state

Partially updates metadata in the resolved language or changes the global active state. Deactivation is refused while any reference exists. Requires media:write.

Authorizations:
ApiKeyAuth
path Parameters
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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

Request Body schema: application/json
required
non-empty
title
string <= 255 characters
altText
string <= 255 characters
description
string <= 10000 characters
active
boolean

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "altText": "string",
  • "description": "string",
  • "active": true
}

Response samples

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

Deactivate an unused media asset

Deactivates the global asset without deleting its stored file or metadata. Any existing reference produces 409. Requires media:write.

Authorizations:
ApiKeyAuth
path Parameters
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.

Responses

Response samples

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

Inspect visible media usage

Returns product, variant, category, and manufacturer references visible in the resolved shop. References outside the API client's authorized catalog boundary are omitted. Requires media:read.

Authorizations:
ApiKeyAuth
path Parameters
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.

Responses

Response samples

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

Replace media-collection assignments

Authoritatively replaces the global collection membership of one media asset. An empty array clears all memberships. Requires media:write.

Authorizations:
ApiKeyAuth
path Parameters
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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Responses

Request samples

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

Response samples

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

List media collections

Returns the global hierarchical media-collection registry, including inactive entries. Requires media: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.

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": [ ]
}

Create a media collection

Creates one global collection below an optional existing parent. Parent cycles are rejected. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires media: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.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
name
required
string [ 1 .. 120 ] characters
description
string <= 10000 characters
parentCollectionId
integer or null >= 1
sortOrder
integer [ 0 .. 2147483647 ]
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "parentCollectionId": 1,
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Get a media collection

Returns one global media collection. Requires media:read.

Authorizations:
ApiKeyAuth
path Parameters
mediaCollectionId
required
integer [ 1 .. 2147483647 ]
Example: 17

Positive global media-collection 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": [ ]
}

Update a media collection

Partially updates global collection metadata, order, parent, or lifecycle state while preventing hierarchy cycles. Requires media:write.

Authorizations:
ApiKeyAuth
path Parameters
mediaCollectionId
required
integer [ 1 .. 2147483647 ]
Example: 17

Positive global media-collection 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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 120 ] characters
description
string <= 10000 characters
parentCollectionId
integer or null >= 1
sortOrder
integer [ 0 .. 2147483647 ]
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "parentCollectionId": 1,
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Delete an empty media collection

Deletes a collection only when no child collection or asset membership references it. Media assets are never deleted by this operation. Requires media:write.

Authorizations:
ApiKeyAuth
path Parameters
mediaCollectionId
required
integer [ 1 .. 2147483647 ]
Example: 17

Positive global media-collection 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": [ ]
}

Catalog media roles

Shop-authorized product and variant downloads and external-video assignments

Get a product media role

Returns the ordered assets assigned to the supported downloads role without exposing storage paths. The product must be visible in the resolved shop. Requires both media:read and catalog:read.

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

Positive product identifier.

mediaRole
required
string
Value: "downloads"
Example: downloads

Public catalog media role. The current bounded contract supports downloads.

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 product media role

Authoritatively replaces the ordered product downloads role with distinct active assets while preserving gallery and every other role. Requires both media:write and catalog:write.

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

Positive product identifier.

mediaRole
required
string
Value: "downloads"
Example: downloads

Public catalog media role. The current bounded contract supports downloads.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Responses

Request samples

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

Response samples

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

Get product external videos

Returns the authoritative ordered YouTube and Vimeo references for a product visible in the resolved shop. Requires both media:read and catalog:read.

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.

Responses

Response samples

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

Replace product external videos

Authoritatively replaces up to 50 distinct supported YouTube or Vimeo references for a visible product. Requires both media:write and catalog:write.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Get a variant media role

Returns the ordered assets assigned to the supported variant downloads role without exposing storage paths. The variant must be visible in the resolved shop. Requires both media:read and catalog:read.

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

Positive product variant identifier.

mediaRole
required
string
Value: "downloads"
Example: downloads

Public catalog media role. The current bounded contract supports downloads.

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 variant media role

Authoritatively replaces the ordered variant downloads role with distinct active assets while preserving gallery and every other role. Requires both media:write and catalog:write.

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

Positive product variant identifier.

mediaRole
required
string
Value: "downloads"
Example: downloads

Public catalog media role. The current bounded contract supports downloads.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Responses

Request samples

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

Response samples

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

Get variant external videos

Returns the authoritative ordered YouTube and Vimeo references for a variant visible in the resolved shop. Requires both media:read and catalog:read.

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": [ ]
}

Replace variant external videos

Authoritatively replaces up to 50 distinct supported YouTube or Vimeo references for a visible variant. Requires both media:write and catalog:write.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Responses

Request samples

Content type
application/json
{}

Response samples

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

Variants

Product variant and variant-group management

Get the product variant-option selection

Returns the ordered variant groups and values currently enabled for one product in the resolved shop. The selection is product master data; shop context authorizes access and language context localizes names. Assigned inactive groups and values remain visible so callers can explicitly remove or retain legacy selections.

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 the product variant-option selection

Replaces the complete set of variant groups and values enabled for one product. Group array order becomes authoritative display and combination order. Each valueIds array is a set; returned values use their global definition order. At most 8 groups and 50 total values are accepted. Every group requires at least one value. Active definitions may be newly selected; already assigned inactive definitions may only be retained or removed. An empty groups array clears the selection.

Existing product variants are never deleted or rewritten when the selection changes. Authentication with catalog: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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Complete desired selection in authoritative order.

Responses

Request samples

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

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. Supply an optional Idempotency-Key to make exact retries safe for 24 hours.

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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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": [ ]
}

Generate missing product variants

Creates the missing Cartesian combinations from the product's stored variant-option selection. The operation is additive and retry-safe: matching variants are reported as existing, concurrently inserted combinations as conflict, and no existing or obsolete variant is deleted or changed.

The stored selection must contain only active definitions and may produce at most 250 combinations. Send an empty JSON object; option IDs are deliberately not accepted here so selection and generation remain separate explicit operations. Authentication with catalog: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
<= 0 properties
object (ProductVariantGenerationRequest) <= 0 properties

This operation accepts an empty JSON object only.

Responses

Request samples

Content type
application/json
{ }

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.

sku
string [ 1 .. 255 ] characters
Example: sku=VARIANT-51

Exact effective variant SKU/article-number filter. Variant values fall back to the parent product when the variant does not store its own SKU. Unlike q, this parameter does not perform substring matching.

ean
string [ 1 .. 64 ] characters
Example: ean=7612345678999

Exact effective variant EAN filter. Variant values fall back to the parent product when the variant does not store its own EAN. Unlike q, this parameter does not perform substring matching.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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 is one of the bounded unused-record cleanup operations exposed for product authoring.

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": [ ]
}

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": [ ]
}

Create a variant group

Creates one global variant group and its name in the resolved language. The name is globally unique without regard to case. sortOrder defaults to the next available position and active defaults to true. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Authentication with catalog:write 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.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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

Group name in the resolved request language.

sortOrder
integer [ 0 .. 2147483647 ]

Omit to append after the current variant groups.

active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "Color",
  • "sortOrder": 10,
  • "active": true
}

Response samples

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

Get a variant group

Returns one global variant group with every localized value, independently of active state. The resolved shop authorizes access and the resolved language controls localized names.

Authorizations:
ApiKeyAuth
path Parameters
variantGroupId
required
integer [ 1 .. 2147483647 ]
Example: 12

Positive global variant-group 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 variant group

Partially updates the group. name targets the resolved language; a name written in the installation default language also changes the globally unique master name. Omitted fields remain unchanged. Use active: false for reversible deactivation. Definitions and existing product variants are never deleted by this API.

Authorizations:
ApiKeyAuth
path Parameters
variantGroupId
required
integer [ 1 .. 2147483647 ]
Example: 12

Positive global variant-group 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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Group name in the resolved request language.

sortOrder
integer [ 0 .. 2147483647 ]
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Create a variant-group value

Creates one value in the selected global group and stores its label in the resolved language. Values are unique within their group without regard to case. sortOrder appends after the current values and active defaults to true. Supply an optional Idempotency-Key to make exact retries safe for 24 hours.

Authorizations:
ApiKeyAuth
path Parameters
variantGroupId
required
integer [ 1 .. 2147483647 ]
Example: 12

Positive global variant-group 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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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

Value label in the resolved request language.

swatchColor
string or null^#?[0-9A-Fa-f]{6}$|^$

Optional six-digit hexadecimal color; null or empty clears it.

sortOrder
integer [ 0 .. 2147483647 ]

Omit to append after the current values.

active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "value": "Red",
  • "swatchColor": "#e63946",
  • "sortOrder": 10,
  • "active": true
}

Response samples

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

Update a variant-group value

Partially updates one value belonging to the selected group. value targets the resolved language; the installation default language also changes the group's case-insensitive uniqueness key. Set swatchColor to null or an empty string to clear it. Use active: false for reversible deactivation; existing product selections and variants remain intact.

Authorizations:
ApiKeyAuth
path Parameters
variantGroupId
required
integer [ 1 .. 2147483647 ]
Example: 12

Positive global variant-group identifier.

valueId
required
integer [ 1 .. 2147483647 ]
Example: 24

Positive value identifier belonging to the selected variant group.

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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Value label in the resolved request language.

swatchColor
string or null^#?[0-9A-Fa-f]{6}$|^$

Six-digit hexadecimal color; null or empty clears it.

sortOrder
integer [ 0 .. 2147483647 ]
active
boolean

Responses

Request samples

Content type
application/json
{
  • "value": "string",
  • "swatchColor": "string",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Catalog pricing

Resolved product and variant prices and explicit price overrides

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Get a stored product shop price override

Returns active, non-scheduled stored product override tiers for one assigned, active, non-primary shop and selected currency. inherited is true and priceTiers is empty when no override is stored. This is a persistence readback, not the fully resolved effective price.

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.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Get a stored variant shop price override

Returns active, non-scheduled stored variant override tiers for one assigned, active, non-primary shop and selected currency. inherited is true and priceTiers is empty when no variant override is stored. This is a persistence readback, not the fully resolved effective price.

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.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Get a stored global variant price-list override

Returns the stored quantity tiers for one variant, global price list, and resolved currency. inherited is true and priceTiers is empty when no override is stored. The resolved shop verifies access to the variant but does not scope the global override. Requires catalog:read.

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.

Responses

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Catalog data

Categories, manufacturers, markings, specifications, units, and delivery times

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. Supply an optional Idempotency-Key to make exact retries safe for 24 hours.

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.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Get accessible category shop assignments

Returns the authoritative category assignment set within the authenticated API client's shop-access boundary. The category must be assigned to the resolved shop. Each item includes the shop-specific catalog display settings stored with that assignment. Assignments to shops outside the client's access are omitted and remain preserved by category updates.

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": [ ]
}

Get category specification and filter assignments

Returns the global, shared-catalog assignment in explicit order. The resolved shop is used only to authorize visibility of the category; assignment ownership is never inferred from that shop.

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": [ ]
}

Replace category specification and filter assignments

Authoritatively replaces the shared ordered definition list. Active definitions may be newly assigned; existing inactive definitions may be retained or removed. Storefront facets use this persisted allow-list together with each definition's active, filterable, and storefront-visible state. Requires catalog:write and visibility of the category in the resolved authorized shop.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Responses

Request samples

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

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. Supply an optional Idempotency-Key to make exact retries safe for 24 hours.

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.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Get accessible manufacturer shop assignments

Returns the authoritative manufacturer assignment set within the authenticated API client's shop-access boundary. The manufacturer must be assigned to the resolved shop. Assignments to shops outside the client's access are omitted and remain preserved by manufacturer updates.

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": [ ]
}

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

Returns localized global layout groups in deterministic order, including inactive groups.

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": [ ]
}

Create a specification group

Creates global layout master data; name and description target the resolved language. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires catalog: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.

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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
key
required
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
required
string [ 1 .. 255 ] characters
description
string <= 10000 characters
Default: ""
sortOrder
integer [ 0 .. 2147483647 ]
Default: 0
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "description": "",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Get a specification group

Returns one localized global layout group, including inactive master data.

Authorizations:
ApiKeyAuth
path Parameters
specificationGroupId
required
integer [ 1 .. 2147483647 ]
Example: 4

Positive global specification-group 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 or deactivate a specification group

Partially updates global master data. Use active: false for reversible deactivation. Requires catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
specificationGroupId
required
integer [ 1 .. 2147483647 ]
Example: 4

Positive global specification-group 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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

Request Body schema: application/json
required
non-empty
key
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
string [ 1 .. 255 ] characters
description
string <= 10000 characters
sortOrder
integer [ 0 .. 2147483647 ]
active
boolean

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "description": "string",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

List specification sets

Returns localized global sets and their authoritatively ordered layouts, including inactive records.

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": [ ]
}

Create a specification set

Creates an empty global specification set in the resolved language. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires catalog: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.

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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
key
required
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
required
string [ 1 .. 255 ] characters
description
string <= 10000 characters
Default: ""
sortOrder
integer [ 0 .. 2147483647 ]
Default: 0
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "description": "",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Get a specification set

Returns one localized global set with its complete deterministic layout, including inactive items.

Authorizations:
ApiKeyAuth
path Parameters
specificationSetId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global specification-set 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 or deactivate a specification set

Partially updates global set master data. Use active: false for reversible deactivation. Requires catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
specificationSetId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global specification-set 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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

Request Body schema: application/json
required
non-empty
key
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
string [ 1 .. 255 ] characters
description
string <= 10000 characters
sortOrder
integer [ 0 .. 2147483647 ]
active
boolean

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "description": "string",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Replace a specification-set layout

Replaces the complete ordered layout. Definitions and optional groups must be active when newly referenced; existing inactive references may be retained or removed. Definitions already referenced by typed product values cannot be removed. Requires catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
specificationSetId
required
integer [ 1 .. 2147483647 ]
Example: 7

Positive global specification-set 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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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

Responses

Request samples

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

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": [ ]
}

Create a typed specification definition

Creates global specification master data for any supported value type. Option values are authored through the nested option endpoint. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires catalog: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.

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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
key
required
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
required
string [ 1 .. 255 ] characters
description
string <= 10000 characters
Default: ""
valueType
required
string
Enum: "text" "number" "decimal" "boolean" "date" "single_option" "multi_option"
unitId
integer or null >= 1
sortOrder
integer [ 0 .. 2147483647 ]
Default: 0
required
boolean
Default: false
filterable
boolean
Default: false
searchable
boolean
Default: false
comparable
boolean
Default: false
storefrontVisible
boolean
Default: true
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "description": "",
  • "valueType": "text",
  • "unitId": 1,
  • "sortOrder": 0,
  • "required": false,
  • "filterable": false,
  • "searchable": false,
  • "comparable": false,
  • "storefrontVisible": true,
  • "active": true
}

Response samples

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

Get a typed specification definition

Returns one localized global definition with all option values, including inactive records.

Authorizations:
ApiKeyAuth
path Parameters
specificationDefinitionId
required
integer [ 1 .. 2147483647 ]
Example: 11

Positive global specification-definition 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 or deactivate a typed specification definition

Partially updates global master data. A value type cannot change while typed product values reference the definition. Use active: false for reversible deactivation. Requires catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
specificationDefinitionId
required
integer [ 1 .. 2147483647 ]
Example: 11

Positive global specification-definition 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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

Request Body schema: application/json
required
non-empty
key
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
string [ 1 .. 255 ] characters
description
string <= 10000 characters
valueType
string
Enum: "text" "number" "decimal" "boolean" "date" "single_option" "multi_option"
unitId
integer or null >= 1
sortOrder
integer [ 0 .. 2147483647 ]
required
boolean
filterable
boolean
searchable
boolean
comparable
boolean
storefrontVisible
boolean
active
boolean

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "description": "string",
  • "valueType": "text",
  • "unitId": 1,
  • "sortOrder": 0,
  • "required": true,
  • "filterable": true,
  • "searchable": true,
  • "comparable": true,
  • "storefrontVisible": true,
  • "active": true
}

Response samples

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

Create an option value

Creates a localized option for a single_option or multi_option definition. Supply an optional Idempotency-Key to make exact retries safe for 24 hours. Requires catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
specificationDefinitionId
required
integer [ 1 .. 2147483647 ]
Example: 11

Positive global specification-definition 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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
key
required
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
required
string [ 1 .. 255 ] characters
sortOrder
integer [ 0 .. 2147483647 ]
Default: 0
active
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "active": true
}

Response samples

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

Update or deactivate an option value

Referenced options cannot be deactivated. Omitted fields remain unchanged. Requires catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
specificationDefinitionId
required
integer [ 1 .. 2147483647 ]
Example: 11

Positive global specification-definition identifier.

optionId
required
integer [ 1 .. 2147483647 ]
Example: 21

Positive option identifier belonging to the selected definition.

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
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

Request Body schema: application/json
required
non-empty
key
string [ 1 .. 120 ] characters ^[a-z0-9_]+$
name
string [ 1 .. 255 ] characters
sortOrder
integer [ 0 .. 2147483647 ]
active
boolean

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "sortOrder": 0,
  • "active": true
}

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": [ ]
}

Catalog synchronization

Capability discovery, namespaced external identities, and safe catalog-create retries

Discover catalog synchronization capabilities

Returns the approved external-reference resource types and their operation-specific scopes, the deployed API build, and the bounded catalog-import job, create-idempotency, optimistic-concurrency, upload, batch, and endpoint-limit contracts. Capability discovery requires at least one catalog or media read/write scope but does not grant any listed scope.

Authorizations:
ApiKeyAuth

Responses

Response samples

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

Create and process one bounded catalog import job

Persists a durable import job and processes its first chunk immediately. dry_run and apply use the same product-create validation; dry runs never write products. The whole request is rejected before processing when it exceeds 500 records, 2 MiB, 64 KiB per record, or a chunk size of 50. Currently only product.create is supported. Use the operation's advertised normal endpoint for all other catalog mutations. Requires catalog:write and a resolved commerce 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.

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
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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

Request Body schema: application/json
required
mode
required
string
Enum: "dry_run" "apply"
chunkSize
integer [ 1 .. 50 ]
Default: 25
required
Array of objects (CatalogImportJobRecord) [ 1 .. 500 ] items

Responses

Request samples

Content type
application/json
{
  • "mode": "dry_run",
  • "chunkSize": 25,
  • "records": [
    ]
}

Response samples

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

Inspect a catalog import job

Returns durable progress, the persisted commerce context, the next record cursor, counts, and retention deadline. Jobs are visible only to their creating API client while its assignment to the stored shop remains active. Requires catalog:read or catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
jobId
required
integer [ 1 .. 2147483647 ]
Example: 27

Positive durable catalog import job identifier.

Responses

Response samples

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

List stable per-record catalog import results

Returns results in immutable ascending record order. Successful apply records include the created resource; dry-run successes use valid; failed records include their stable validation error. Requires catalog:read or catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
jobId
required
integer [ 1 .. 2147483647 ]
Example: 27

Positive durable catalog import job 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.

Responses

Response samples

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

Process the next catalog import job chunk

Claims and processes at most one pending chunk. Send the nextRecordIndex from the latest job representation as expectedNextRecordIndex. Repeating an already completed cursor is a safe replay and does not execute that chunk again; an ahead cursor or concurrently processing job returns 409. Requires catalog:write.

Authorizations:
ApiKeyAuth
path Parameters
jobId
required
integer [ 1 .. 2147483647 ]
Example: 27

Positive durable catalog import job identifier.

Request Body schema: application/json
required
expectedNextRecordIndex
required
integer >= 1

Exact nextRecordIndex from the latest persisted job representation.

Responses

Request samples

Content type
application/json
{
  • "expectedNextRecordIndex": 26
}

Response samples

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

Resolve an external catalog identity

Resolves a mapping owned by the authenticated API client and then revalidates the target through the current commerce context. Missing, deleted, unassigned, or otherwise hidden targets all return the same 404 external_reference_not_found response. Requires the read scope advertised for the selected resource type by /catalog-capabilities.

Authorizations:
ApiKeyAuth
path Parameters
namespace
required
string [ 1 .. 64 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Example: erp

Caller-owned namespace that prevents collisions between source systems.

resourceType
required
string
Enum: "accessory_group" "category" "manufacturer" "media_asset" "media_collection" "product" "specification_definition" "specification_group" "specification_option" "specification_set" "variant" "variant_group" "variant_group_value"
Example: product

Approved catalog resource type from the capability endpoint.

externalId
required
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,189}$
Example: product-501

Stable resource identity within the caller's namespace.

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": [ ]
}

Bind an external catalog identity

Creates a stable mapping from the caller's namespace and external ID to one currently visible catalog resource. Repeating the identical binding returns 200; attempting to move the identity to another target returns 409 external_reference_conflict. The mapping is owned by the authenticated API client and remains separate from shop assignment. Requires the write scope advertised for the resource type.

Authorizations:
ApiKeyAuth
path Parameters
namespace
required
string [ 1 .. 64 ] characters ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Example: erp

Caller-owned namespace that prevents collisions between source systems.

resourceType
required
string
Enum: "accessory_group" "category" "manufacturer" "media_asset" "media_collection" "product" "specification_definition" "specification_group" "specification_option" "specification_set" "variant" "variant_group" "variant_group_value"
Example: product

Approved catalog resource type from the capability endpoint.

externalId
required
string [ 1 .. 190 ] characters ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,189}$
Example: product-501

Stable resource identity within the caller's namespace.

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
resourceId
required
integer [ 1 .. 2147483647 ]

Responses

Request samples

Content type
application/json
{
  • "resourceId": 42
}

Response samples

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

Price lists

Global price-list discovery and controlled writes

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.

header Parameters
If-Match
required
string^"sha256:[a-f0-9]{64}"$
Example: "sha256:0f4b2637c937a31ca2916881875e8c92c88155f84467d5607e8e74d44ad36b1f"

Strong validator from the latest authoritative GET response. The mutation is rejected with 412 when the representation changed after it was read. Re-read the same resource and retry deliberately with the new validator.

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": [ ]
}

Customers

Shop-scoped customer identities and supporting customer master data

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": [ ]
}

Customer lifecycle

Customer registrations, shop assignments, and newsletter consent

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": [ ]
}

Customer addresses

Shop-scoped customer address management

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 B2B company master-data management

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": [ ]
}

Company addresses

Shop-scoped B2B company address management

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": [ ]
}

Company members

B2B company membership management

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": [ ]
}

Company shops

Authorized B2B company shop assignments

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": [ ]
}

Orders

Shop-isolated order reads and status 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": [ ]
}

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": [ ]
}

Refunds

Persisted order refund reads and controlled writes

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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": [ ]
}

Order documents

Generation, delivery, download, and deletion of immutable order documents

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": [ ]
}

Order communications

Template-driven order communication and delivery history

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": [ ]
}

Shipments

Order shipment and tracking management

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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 for 24 hours. Keys are scoped to the authenticated API client and shared across the approved catalog create classes. An exact replay returns the original response data with 200 and meta.idempotentReplay: true; reuse for different normalized request data returns 409 idempotency_conflict.

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": [ ]
}

Coupons

Shop-scoped coupon and coupon-code 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": [ ]
}

Vouchers

Shop-scoped voucher lifecycle and balance management

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": [ ]
}

Price actions

Shop-scoped scheduled catalog price actions

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": [ ]
}

Abandoned carts

Privacy-bounded abandoned-cart discovery

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": [ ]
}

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": [ ]
}

MCP

Effective Model Context Protocol configuration for authenticated API clients

Get effective MCP capabilities

Returns whether the MCP integration is enabled, the globally enabled MCP tool groups, and the authenticated API client's effective scopes and shop assignments together with the deployed API build. This endpoint authenticates the sidecar without giving it database access. It does not grant scopes or shop access.

Authorizations:
ApiKeyAuth

Responses

Response samples

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