Skip to content

Public API

The complete reference for every public endpoint, generated from the services' own OpenAPI documents, with a console to call any of them from your browser. JSON over HTTPS, bearer tokens, RFC 7807 problem details on every error.

  • Base URLhttps://marketplace-api.paysera.com
  • AuthBearer token (OAuth 2.0)
  • Errorsapplication/problem+json
  • Coverage7 services · 297 operations

How authentication works

Every request carries Authorization: Bearer <token>. Tokens are issued by Paysera Marketplace sign-in (OAuth 2.0). There are no API keys: an integration authenticates as an agent — a delegated identity the seller creates and approves from their dashboard, with its own client id and secret. Each operation below names the capability the agent needs, for example products:read_write.

  1. Create an agent

    In the seller dashboard under Team & access → Agents, create an agent for your integration and choose its capabilities.

  2. Copy its credential

    You get a client id (agt_…) and a secret. Store the secret server-side; it can be rotated with a 24-hour overlap.

  3. Request a token

    Exchange the credential for an access token with the client-credentials grant.

  4. Call the API

    Send the token as a bearer. It is short-lived; request a new one when you get 401.

bashGet a token (client credentials)
curl -X POST https://marketplace-api.paysera.com/auth/realms/marketplace/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=agt_7tvsvcagent0001 \
  -d client_secret=$AGENT_SECRET

Trying things out as yourself? Your own seller sign-in also yields a token (the password grant on the same endpoint). Use it for exploration only; production integrations use an agent so access can be limited and revoked without touching your account.

Endpoint reference

Pick a service, then a group. Every operation shows its parameters, request and response schemas, examples, and the capability an agent needs. Try it loads the operation into the console on the right.

Pagination
Cursor-based: after / before / limit; responses carry _metadata.hasMore and _metadata.nextCursor.
Errors
RFC 7807 application/problem+json on every non-2xx — see Errors.
Units
Money as integer cents + ISO 4217 code; weight in grams; dimensions in millimetres. Never converted server-side.
Ids & versions
Ids are UUIDs (v7, time-ordered). The API version is in the path: /rest/v1.
Capabilities
Each operation names the capability an agent needs, e.g. products:read_write; humans are checked by role.

Seller Profile 3 operations

POST/rest/v1/seller/profilememberCreate seller profile

Creates a seller profile for the authenticated user. Fails with 409 if a profile already exists. Available to any active member of the account; no area capability is required.

Requires

member

Request body · application/json

  • businessNamestringrequiredLegal business name
  • businessAddressstringrequiredRegistered business address
  • registrationNumberstringrequiredBusiness registration number
  • vatIdstringVAT identification number (optional)

Response · 201

  • idstringSeller profile ID (matches the seller's user ID)
  • businessNamestring
  • businessAddressstring
  • registrationNumberstring
  • vatIdstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/profile
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "businessName": "Acme Corp",
  "businessAddress": "123 Main St, Vilnius, Lithuania",
  "registrationNumber": "123456789",
  "vatId": "LT123456789"
}
jsonResponse · 201
{
  "id": "usr_01JCX4B2M6",
  "businessName": "Acme Corp",
  "businessAddress": "123 Main St, Vilnius, Lithuania",
  "registrationNumber": "123456789",
  "vatId": "LT123456789",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
write#
PUT/rest/v1/seller/profilememberUpdate seller profile

Updates the seller profile for the authenticated user. Fails with 404 if no profile exists. Available to any active member of the account; no area capability is required.

Requires

member

Request body · application/json

  • businessNamestringrequiredLegal business name
  • businessAddressstringrequiredRegistered business address
  • registrationNumberstringrequiredBusiness registration number
  • vatIdstringVAT identification number (optional)

Response · 200

  • idstringSeller profile ID (matches the seller's user ID)
  • businessNamestring
  • businessAddressstring
  • registrationNumberstring
  • vatIdstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/profile
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "businessName": "Acme Corp",
  "businessAddress": "123 Main St, Vilnius, Lithuania",
  "registrationNumber": "123456789",
  "vatId": "LT123456789"
}
jsonResponse · 200
{
  "id": "usr_01JCX4B2M6",
  "businessName": "Acme Corp",
  "businessAddress": "123 Main St, Vilnius, Lithuania",
  "registrationNumber": "123456789",
  "vatId": "LT123456789",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
write#
GET/rest/v1/seller/accounts/{accountId}/profilememberGet seller profile

Returns the seller profile for the account named in the path — the caller's own account, or one they are a member of. Membership is validated server-side; a non-member gets 404.

Requires

member

Path parameters

  • accountIdstringrequiredThe seller account (an owner's UserId) the request acts on — the caller's own account, or one they are a member of. Membership is validated server-side (a non-member gets 404, never another account's data).

Response · 200

  • idstringSeller profile ID (matches the seller's user ID)
  • businessNamestring
  • businessAddressstring
  • registrationNumberstring
  • vatIdstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/accounts/Account id/profile
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "usr_01JCX4B2M6",
  "businessName": "Acme Corp",
  "businessAddress": "123 Main St, Vilnius, Lithuania",
  "registrationNumber": "123456789",
  "vatId": "LT123456789",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
read#

Seller Stores 8 operations

POST/rest/v1/seller/storesmemberCreate store

Creates a new store for the authenticated seller. Available to any active member of the account; no area capability is required.

Requires

member

Request body · application/json

  • namestringrequiredStore name
  • descriptionstringrequiredStore description

Response · 201

  • idstring · uuid
  • userIdstringOwner user identifier
  • namestring
  • descriptionstring
  • statusstringOne of: inactive · active · suspended
  • logoUrlstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "My Electronics Store",
  "description": "Selling quality electronics"
}
jsonResponse · 201
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-000000000042",
  "name": "My Electronics Store",
  "description": "Selling quality electronics",
  "status": "inactive",
  "logoUrl": "https://storage.example.com/store-logos/abc.png",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
write#
GET/rest/v1/seller/accounts/{accountId}/storesmemberList stores

Returns a paginated list of stores for the account named in the path — the caller's own account, or one they are a member of. Membership is validated server-side; a non-member gets 404. This is the fix for the "empty cabinet" seen by a…

Requires

member

Path parameters

  • accountIdstringrequiredThe seller account (an owner's UserId) the request acts on — the caller's own account, or one they are a member of. Membership is validated server-side (a non-member gets 404, never another account's data).

Query parameters

  • afterstring · uuidCursor for forward pagination (UUID of last item on previous page)
  • beforestring · uuidCursor for backward pagination (UUID of first item on previous page)
  • limitintegerNumber of items per page
  • includeTotalCountbooleanInclude total count in response metadata

Response · 200

  • itemsarray<object>
    • idstring · uuid
    • userIdstringOwner user identifier
    • namestring
    • descriptionstring
    • statusstringOne of: inactive · active · suspended
    • logoUrlstring
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/accounts/Account id/stores
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01932a00-0000-7000-8000-000000000001",
      "userId": "01932a00-0000-7000-8000-000000000042",
      "name": "My Electronics Store",
      "description": "Selling quality electronics",
      "status": "inactive",
      "logoUrl": "https://storage.example.com/store-logos/abc.png",
      "createdAt": "2026-04-01T12:34:56.789012Z",
      "updatedAt": "2026-04-01T12:34:56.789012Z"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-7081-7293-a4a5-102132435467",
    "prevCursor": "01914d0e-b4c5-76d7-a8e9-546576879aab",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/seller/stores/{storeId}memberGet store

Returns a specific store for the authenticated seller. Available to any active member of the account; no area capability is required.

Requires

member

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • userIdstringOwner user identifier
  • namestring
  • descriptionstring
  • statusstringOne of: inactive · active · suspended
  • logoUrlstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-000000000042",
  "name": "My Electronics Store",
  "description": "Selling quality electronics",
  "status": "inactive",
  "logoUrl": "https://storage.example.com/store-logos/abc.png",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
read#
PATCH/rest/v1/seller/stores/{storeId}administratorUpdate store

Updates an existing store for the authenticated seller. Only provided fields are updated. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive 403…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • namestringStore name
  • descriptionstringStore description

Response · 200

  • idstring · uuid
  • userIdstringOwner user identifier
  • namestring
  • descriptionstring
  • statusstringOne of: inactive · active · suspended
  • logoUrlstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "My Updated Store",
  "description": "Updated description"
}
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-000000000042",
  "name": "My Electronics Store",
  "description": "Selling quality electronics",
  "status": "inactive",
  "logoUrl": "https://storage.example.com/store-logos/abc.png",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/publishadministratorPublish store

Publishes a store, making it visible to customers. Requires an active delivery option, the same one the shipping-method deactivate refusal counts — an active shipping method with a rated zone, an active location offering pickup, or an…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • userIdstringOwner user identifier
  • namestring
  • descriptionstring
  • statusstringOne of: inactive · active · suspended
  • logoUrlstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/publish
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-000000000042",
  "name": "My Electronics Store",
  "description": "Selling quality electronics",
  "status": "inactive",
  "logoUrl": "https://storage.example.com/store-logos/abc.png",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/unpublishadministratorUnpublish store

Unpublishes a store, removing it from customer visibility. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive 403 `/errors/forbidden`.

Requires

administrator

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • userIdstringOwner user identifier
  • namestring
  • descriptionstring
  • statusstringOne of: inactive · active · suspended
  • logoUrlstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/unpublish
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-000000000042",
  "name": "My Electronics Store",
  "description": "Selling quality electronics",
  "status": "inactive",
  "logoUrl": "https://storage.example.com/store-logos/abc.png",
  "createdAt": "2026-04-01T12:34:56.789012Z",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
write#

Uploads 1 operation

POST/rest/v1/uploadsauthenticatedCreate an upload

Uploads a file for a consumer-defined purpose and returns a signed upload token (`uploadId`) that a later command uses to attach the file to a resource. Send as `multipart/form-data` with a `file` field and a `purpose` field. Supported…

Requires

authenticated

Request body · multipart/form-data

  • filestring · binaryrequiredFile payload
  • purposestringrequiredConsumer-defined upload purpose. Must be registered in the UploadPurposeRegistry.One of: showroom.store.logo · showroom.listing.photo · showroom.listing.import · showroom.store_feedback.photo · showroom.store_feedback.response_photo

Response · 201

  • uploadIdstringOpaque signed token identifying this upload. Pass verbatim to the subsequent attach/claim command.
  • expiresAtintegerEpoch seconds after which this upload token is rejected.
  • mimeTypestringRFC 6838 media type of the stored file.
  • sizeintegerSize of the stored file in bytes.
  • originalNamestringOriginal file name as sent by the client (not trusted for storage).
  • purposestringResolved purpose for this upload (consumer-defined).

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/uploads
Authorization: Bearer $TOKEN
jsonResponse · 201
{
  "uploadId": "Upload id",
  "expiresAt": 1714060800,
  "mimeType": "image/jpeg",
  "size": 204800,
  "originalName": "logo.png",
  "purpose": "showroom.store.logo"
}
write#

Seller Store Settings 2 operations

GET/rest/v1/seller/stores/{storeId}/settings/refund-policymemberGet refund policy

Returns the refund policy for a store. When no policy has been configured, refundWindow, policyText, and updatedAt are all null. Available to any active member of the account; no area capability is required.

Requires

member

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • storeIdstring · uuid
  • refundWindowintegerRefund window in days (0-365); null when no policy has been configured.
  • policyTextstringCustom refund policy text
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/settings/refund-policy
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "storeId": "01932a00-0000-7000-8000-000000000001",
  "refundWindow": 30,
  "policyText": "Policy text",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
read#
PUT/rest/v1/seller/stores/{storeId}/settings/refund-policyadministratorUpdate refund policy

Updates the refund policy for a store. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive 403 `/errors/forbidden`.

Requires

administrator

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • refundWindowintegerrequiredRefund window in days (0-365)
  • policyTextstringCustom refund policy text (max 5000 characters)

Response · 200

  • storeIdstring · uuid
  • refundWindowintegerRefund window in days (0-365); null when no policy has been configured.
  • policyTextstringCustom refund policy text
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/settings/refund-policy
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "refundWindow": 30,
  "policyText": "Full refund within 14 days of purchase."
}
jsonResponse · 200
{
  "storeId": "01932a00-0000-7000-8000-000000000001",
  "refundWindow": 30,
  "policyText": "Policy text",
  "updatedAt": "2026-04-01T12:34:56.789012Z"
}
write#

Distribution — Locations 13 operations

POST/rest/v1/seller/stores/{storeId}/locationsstock:read_writeRegister a new location

Creates a new distribution location for a store. The location is created in inactive state by default. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • namestringrequiredLocation display name
  • addressobjectrequired
    • streetstringrequiredStreet address
    • citystringrequiredCity name
    • postalCodestringrequiredPostal code
    • countryCodestringrequiredCountry code (ISO 3166-1 alpha-2)
  • countryCodestringrequiredCountry code (ISO 3166-1 alpha-2)
  • settingsobject
    • shipsOrdersbooleanWhether this location ships orders
    • offersPickupbooleanWhether this location offers customer pickup
    • acceptsReturnsbooleanWhether this location accepts returns
    • workingDaysarray<integer>Working days (1=Monday, 7=Sunday)
    • processingDeadlinestringDaily processing deadline (HH:MM)
    • handlingTimeHoursintegerHandling time in hours after processing deadline
    • contactPhonestringInternal contact phone number
    • contactEmailstringInternal contact email
  • mapPinLatnumber · floatMap pin latitude
  • mapPinLngnumber · floatMap pin longitude
  • pickupConfigobject
    • timeWindowsarray<object>requiredPickup time windows
    • customerNotesstringNotes displayed to customer during pickup

Response · 201

  • idstring · uuid
  • storeIdstring · uuid
  • namestring
  • addressobject
    • streetstring
    • citystring
    • postalCodestring
    • countryCodestring
  • countryCodestringCountry code (ISO 3166-1 alpha-2)
  • mapPinLatnumber · float
  • mapPinLngnumber · float
  • isActiveboolean
  • settingsobject
    • shipsOrdersboolean
    • offersPickupboolean
    • acceptsReturnsboolean
    • workingDaysarray<integer>
    • processingDeadlinestringDaily processing deadline (HH:MM)
    • handlingTimeHoursintegerHandling time in hours after processing deadline
    • contactPhonestring
    • contactEmailstring
  • pickupConfigobject
    • timeWindowsarray<object>
    • customerNotesstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-6f70-7182-9394-0f1021324356/locations
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Vilnius warehouse",
  "address": {
    "street": "Gedimino pr. 1",
    "city": "Vilnius",
    "postalCode": "01103",
    "countryCode": "LT"
  },
  "countryCode": "LT",
  "settings": {
    "shipsOrders": true,
    "offersPickup": false,
    "acceptsReturns": false,
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "processingDeadline": "16:00",
    "handlingTimeHours": 0,
    "contactPhone": "+37061234567",
    "contactEmail": "warehouse@example.com"
  },
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "pickupConfig": {
    "timeWindows": [
      {
        "dayOfWeek": 1,
        "open": "09:00",
        "close": "18:00"
      }
    ],
    "customerNotes": "Ring the doorbell at entrance B"
  }
}
jsonResponse · 201
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "name": "Vilnius warehouse",
  "address": {
    "street": "Gedimino pr. 1",
    "city": "Vilnius",
    "postalCode": "01103",
    "countryCode": "LT"
  },
  "countryCode": "LT",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isActive": true,
  "settings": {
    "shipsOrders": true,
    "offersPickup": false,
    "acceptsReturns": false,
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "processingDeadline": "16:00",
    "handlingTimeHours": 0,
    "contactPhone": "+37061234567",
    "contactEmail": "warehouse@example.com"
  },
  "pickupConfig": {
    "timeWindows": [
      {
        "dayOfWeek": 1,
        "open": "09:00",
        "close": "18:00"
      }
    ],
    "customerNotes": "Ring the doorbell at entrance B"
  },
  "createdAt": "2026-05-01T12:34:56.789012Z",
  "updatedAt": "2026-05-01T12:34:56.789012Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/locationsstock:readList store locations

Returns a paginated list of distribution locations for a store. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • afterstring · uuidCursor for forward pagination (UUID of last item on previous page)
  • beforestring · uuidCursor for backward pagination (UUID of first item on previous page)
  • limitintegerNumber of items per page
  • includeTotalCountbooleanInclude total count in response metadata

Response · 200

  • itemsarray<object>
    • idstring · uuid
    • storeIdstring · uuid
    • namestring
    • addressobject
    • countryCodestringCountry code (ISO 3166-1 alpha-2)
    • mapPinLatnumber · float
    • mapPinLngnumber · float
    • isActiveboolean
    • settingsobject
    • pickupConfigobject
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-6f70-7182-9394-0f1021324356/locations
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01932a00-0000-7000-8000-000000000001",
      "storeId": "01932a00-0000-7000-8000-000000000002",
      "name": "Vilnius warehouse",
      "address": {
        "street": "Gedimino pr. 1",
        "city": "Vilnius",
        "postalCode": "01103",
        "countryCode": "LT"
      },
      "countryCode": "LT",
      "mapPinLat": 54.687157,
      "mapPinLng": 25.279652,
      "isActive": true,
      "settings": {
        "shipsOrders": true,
        "offersPickup": false,
        "acceptsReturns": false,
        "workingDays": [
          1,
          2,
          3,
          4,
          5
        ],
        "processingDeadline": "16:00",
        "handlingTimeHours": 0,
        "contactPhone": "+37061234567",
        "contactEmail": "warehouse@example.com"
      },
      "pickupConfig": {
        "timeWindows": [
          {
            "dayOfWeek": 1,
            "open": "09:00",
            "close": "18:00"
          }
        ],
        "customerNotes": "Ring the doorbell at entrance B"
      },
      "createdAt": "2026-05-01T12:34:56.789012Z",
      "updatedAt": "2026-05-01T12:34:56.789012Z"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "prevCursor": "01914d0e-5e6f-7071-8283-9e0f10213245",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/seller/stores/{storeId}/locations/{locationId}stock:readGet location details

Returns a specific distribution location with full detail including settings and pickup config. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • namestring
  • addressobject
    • streetstring
    • citystring
    • postalCodestring
    • countryCodestring
  • countryCodestringCountry code (ISO 3166-1 alpha-2)
  • mapPinLatnumber · float
  • mapPinLngnumber · float
  • isActiveboolean
  • settingsobject
    • shipsOrdersboolean
    • offersPickupboolean
    • acceptsReturnsboolean
    • workingDaysarray<integer>
    • processingDeadlinestringDaily processing deadline (HH:MM)
    • handlingTimeHoursintegerHandling time in hours after processing deadline
    • contactPhonestring
    • contactEmailstring
  • pickupConfigobject
    • timeWindowsarray<object>
    • customerNotesstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/locations/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "name": "Vilnius warehouse",
  "address": {
    "street": "Gedimino pr. 1",
    "city": "Vilnius",
    "postalCode": "01103",
    "countryCode": "LT"
  },
  "countryCode": "LT",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isActive": true,
  "settings": {
    "shipsOrders": true,
    "offersPickup": false,
    "acceptsReturns": false,
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "processingDeadline": "16:00",
    "handlingTimeHours": 0,
    "contactPhone": "+37061234567",
    "contactEmail": "warehouse@example.com"
  },
  "pickupConfig": {
    "timeWindows": [
      {
        "dayOfWeek": 1,
        "open": "09:00",
        "close": "18:00"
      }
    ],
    "customerNotes": "Ring the doorbell at entrance B"
  },
  "createdAt": "2026-05-01T12:34:56.789012Z",
  "updatedAt": "2026-05-01T12:34:56.789012Z"
}
read#
PATCH/rest/v1/seller/stores/{storeId}/locations/{locationId}stock:read_writeUpdate location details

Updates name, address, country code, or map pin coordinates. Only provided fields are updated. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Request body · application/json

  • namestringLocation display name
  • addressobject
    • streetstringrequiredStreet address
    • citystringrequiredCity name
    • postalCodestringrequiredPostal code
    • countryCodestringrequiredCountry code (ISO 3166-1 alpha-2)
  • countryCodestringCountry code (ISO 3166-1 alpha-2)
  • mapPinLatnumber · floatMap pin latitude
  • mapPinLngnumber · floatMap pin longitude

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • namestring
  • addressobject
    • streetstring
    • citystring
    • postalCodestring
    • countryCodestring
  • countryCodestringCountry code (ISO 3166-1 alpha-2)
  • mapPinLatnumber · float
  • mapPinLngnumber · float
  • isActiveboolean
  • settingsobject
    • shipsOrdersboolean
    • offersPickupboolean
    • acceptsReturnsboolean
    • workingDaysarray<integer>
    • processingDeadlinestringDaily processing deadline (HH:MM)
    • handlingTimeHoursintegerHandling time in hours after processing deadline
    • contactPhonestring
    • contactEmailstring
  • pickupConfigobject
    • timeWindowsarray<object>
    • customerNotesstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/locations/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Kaunas warehouse",
  "address": {
    "street": "Gedimino pr. 1",
    "city": "Vilnius",
    "postalCode": "01103",
    "countryCode": "LT"
  },
  "countryCode": "LT",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652
}
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "name": "Vilnius warehouse",
  "address": {
    "street": "Gedimino pr. 1",
    "city": "Vilnius",
    "postalCode": "01103",
    "countryCode": "LT"
  },
  "countryCode": "LT",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isActive": true,
  "settings": {
    "shipsOrders": true,
    "offersPickup": false,
    "acceptsReturns": false,
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "processingDeadline": "16:00",
    "handlingTimeHours": 0,
    "contactPhone": "+37061234567",
    "contactEmail": "warehouse@example.com"
  },
  "pickupConfig": {
    "timeWindows": [
      {
        "dayOfWeek": 1,
        "open": "09:00",
        "close": "18:00"
      }
    ],
    "customerNotes": "Ring the doorbell at entrance B"
  },
  "createdAt": "2026-05-01T12:34:56.789012Z",
  "updatedAt": "2026-05-01T12:34:56.789012Z"
}
write#
DELETE/rest/v1/seller/stores/{storeId}/locations/{locationId}stock:read_writeDelete a location

Soft-deletes a location. Cannot delete the last active location for a store. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/locations/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
write#
POST/rest/v1/seller/stores/{storeId}/locations/{locationId}/activatestock:read_writeActivate a location

Activates a deactivated location, making it operational for distribution. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • namestring
  • addressobject
    • streetstring
    • citystring
    • postalCodestring
    • countryCodestring
  • countryCodestringCountry code (ISO 3166-1 alpha-2)
  • mapPinLatnumber · float
  • mapPinLngnumber · float
  • isActiveboolean
  • settingsobject
    • shipsOrdersboolean
    • offersPickupboolean
    • acceptsReturnsboolean
    • workingDaysarray<integer>
    • processingDeadlinestringDaily processing deadline (HH:MM)
    • handlingTimeHoursintegerHandling time in hours after processing deadline
    • contactPhonestring
    • contactEmailstring
  • pickupConfigobject
    • timeWindowsarray<object>
    • customerNotesstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/locations/01914d0e-b4c5-76d7-a8e9-546576879aab/activate
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "name": "Vilnius warehouse",
  "address": {
    "street": "Gedimino pr. 1",
    "city": "Vilnius",
    "postalCode": "01103",
    "countryCode": "LT"
  },
  "countryCode": "LT",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isActive": true,
  "settings": {
    "shipsOrders": true,
    "offersPickup": false,
    "acceptsReturns": false,
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "processingDeadline": "16:00",
    "handlingTimeHours": 0,
    "contactPhone": "+37061234567",
    "contactEmail": "warehouse@example.com"
  },
  "pickupConfig": {
    "timeWindows": [
      {
        "dayOfWeek": 1,
        "open": "09:00",
        "close": "18:00"
      }
    ],
    "customerNotes": "Ring the doorbell at entrance B"
  },
  "createdAt": "2026-05-01T12:34:56.789012Z",
  "updatedAt": "2026-05-01T12:34:56.789012Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/locations/{locationId}/deactivatestock:read_writeDeactivate a location

Deactivates a location. Cannot deactivate the last active location for a store. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • namestring
  • addressobject
    • streetstring
    • citystring
    • postalCodestring
    • countryCodestring
  • countryCodestringCountry code (ISO 3166-1 alpha-2)
  • mapPinLatnumber · float
  • mapPinLngnumber · float
  • isActiveboolean
  • settingsobject
    • shipsOrdersboolean
    • offersPickupboolean
    • acceptsReturnsboolean
    • workingDaysarray<integer>
    • processingDeadlinestringDaily processing deadline (HH:MM)
    • handlingTimeHoursintegerHandling time in hours after processing deadline
    • contactPhonestring
    • contactEmailstring
  • pickupConfigobject
    • timeWindowsarray<object>
    • customerNotesstring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/locations/01914d0e-c5d6-77e8-b9fa-6576879aabbc/deactivate
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01932a00-0000-7000-8000-000000000001",
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "name": "Vilnius warehouse",
  "address": {
    "street": "Gedimino pr. 1",
    "city": "Vilnius",
    "postalCode": "01103",
    "countryCode": "LT"
  },
  "countryCode": "LT",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isActive": true,
  "settings": {
    "shipsOrders": true,
    "offersPickup": false,
    "acceptsReturns": false,
    "workingDays": [
      1,
      2,
      3,
      4,
      5
    ],
    "processingDeadline": "16:00",
    "handlingTimeHours": 0,
    "contactPhone": "+37061234567",
    "contactEmail": "warehouse@example.com"
  },
  "pickupConfig": {
    "timeWindows": [
      {
        "dayOfWeek": 1,
        "open": "09:00",
        "close": "18:00"
      }
    ],
    "customerNotes": "Ring the doorbell at entrance B"
  },
  "createdAt": "2026-05-01T12:34:56.789012Z",
  "updatedAt": "2026-05-01T12:34:56.789012Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/locations/{locationId}/settingsstock:readGet location settings

Returns the operational settings for a location. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Response · 200

  • shipsOrdersboolean
  • offersPickupboolean
  • acceptsReturnsboolean
  • workingDaysarray<integer>
  • processingDeadlinestringDaily processing deadline (HH:MM)
  • handlingTimeHoursintegerHandling time in hours after processing deadline
  • contactPhonestring
  • contactEmailstring

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/locations/01914d0e-b4c5-76d7-a8e9-546576879aab/settings
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "shipsOrders": true,
  "offersPickup": false,
  "acceptsReturns": false,
  "workingDays": [
    1,
    2,
    3,
    4,
    5
  ],
  "processingDeadline": "16:00",
  "handlingTimeHours": 0,
  "contactPhone": "+37061234567",
  "contactEmail": "warehouse@example.com"
}
read#
PATCH/rest/v1/seller/stores/{storeId}/locations/{locationId}/settingsstock:read_writeChange location settings

Updates operational settings for a location. Only provided fields are updated. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Request body · application/json

  • shipsOrdersbooleanWhether this location ships orders
  • offersPickupbooleanWhether this location offers customer pickup
  • acceptsReturnsbooleanWhether this location accepts returns
  • workingDaysarray<integer>Working days (1=Monday, 7=Sunday)
  • processingDeadlinestringDaily processing deadline (HH:MM)
  • handlingTimeHoursintegerHandling time in hours after processing deadline
  • contactPhonestringInternal contact phone number
  • contactEmailstringInternal contact email

Response · 200

  • shipsOrdersboolean
  • offersPickupboolean
  • acceptsReturnsboolean
  • workingDaysarray<integer>
  • processingDeadlinestringDaily processing deadline (HH:MM)
  • handlingTimeHoursintegerHandling time in hours after processing deadline
  • contactPhonestring
  • contactEmailstring

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/locations/01914d0e-b4c5-76d7-a8e9-546576879aab/settings
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "shipsOrders": true,
  "offersPickup": false,
  "acceptsReturns": false,
  "workingDays": [
    1,
    2,
    3,
    4,
    5
  ],
  "processingDeadline": "16:00",
  "handlingTimeHours": 0,
  "contactPhone": "+37061234567",
  "contactEmail": "warehouse@example.com"
}
jsonResponse · 200
{
  "shipsOrders": true,
  "offersPickup": false,
  "acceptsReturns": false,
  "workingDays": [
    1,
    2,
    3,
    4,
    5
  ],
  "processingDeadline": "16:00",
  "handlingTimeHours": 0,
  "contactPhone": "+37061234567",
  "contactEmail": "warehouse@example.com"
}
write#
PUT/rest/v1/seller/stores/{storeId}/locations/{locationId}/pickup-configstock:read_writeSet pickup configuration

Replaces the pickup configuration for a location. Requires at least one time window. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Request body · application/json

  • timeWindowsarray<object>requiredPickup time windows
    • dayOfWeekintegerrequiredDay of week (1=Monday, 7=Sunday)
    • openstringrequiredOpening time (HH:MM)
    • closestringrequiredClosing time (HH:MM)
  • customerNotesstringNotes displayed to customer during pickup

Response · 200

  • timeWindowsarray<object>
    • dayOfWeekinteger
    • openstring
    • closestring
  • customerNotesstring

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/locations/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/pickup-config
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "timeWindows": [
    {
      "dayOfWeek": 1,
      "open": "09:00",
      "close": "18:00"
    }
  ],
  "customerNotes": "Ring the doorbell at entrance B"
}
jsonResponse · 200
{
  "timeWindows": [
    {
      "dayOfWeek": 1,
      "open": "09:00",
      "close": "18:00"
    }
  ],
  "customerNotes": "Ring the doorbell at entrance B"
}
write#
DELETE/rest/v1/seller/stores/{storeId}/locations/{locationId}/pickup-configstock:read_writeRemove pickup configuration

Removes the pickup configuration from a location. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/locations/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/pickup-config
Authorization: Bearer $TOKEN
write#
GET/rest/v1/seller/stores/{storeId}/locations/{locationId}/itemsstock:readGet location pickup item scope

Returns the pickup item scope of a location: the opaque item references collectable there. Pickup is strict opt-in, so an empty list means the location covers no items. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Response · 200

  • locationIdstring · uuidLocation id
  • itemIdsarray<string>Opaque external item references collectable at this location

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/locations/01914d0e-8192-73a4-b5b6-213243546578/items
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "locationId": "01914d0e-8192-73a4-b5b6-213243546578",
  "itemIds": [
    "item-ref-001",
    "item-ref-002"
  ]
}
read#
PUT/rest/v1/seller/stores/{storeId}/locations/{locationId}/itemsstock:read_writeReplace location pickup item scope

Replaces a location's pickup item scope with exactly the supplied opaque item references. Pickup is strict opt-in: an empty itemIds clears the location (it then covers no items); there is no "applies to all" option. Duplicate references…

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • locationIdstring · uuidrequired

Request body · application/json

  • itemIdsarray<string>Opaque external item references collectable at this location (max 1000); empty means the location covers no items. Pickup is strict opt-in — there is deliberately no appliesToAll field.

Response · 200

  • locationIdstring · uuidLocation id
  • itemIdsarray<string>Opaque external item references collectable at this location

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/locations/01914d0e-8192-73a4-b5b6-213243546578/items
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "itemIds": [
    "item-ref-001",
    "item-ref-002"
  ]
}
jsonResponse · 200
{
  "locationId": "01914d0e-92a3-74b5-86c7-324354657689",
  "itemIds": [
    "item-ref-001",
    "item-ref-002"
  ]
}
write#

Seller Distribution Options 3 operations

GET/rest/v1/seller/stores/{storeId}/distribution-optionsstock:readGet distribution options

Returns the store's distribution channel registry with derived per-channel readiness. Each channel reports whether it is enabled, how many active fulfilling entities back it (active locations for pickup, active shipping methods for…

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • storeIdstring · uuidStore identifier
  • channelsarray<object>Every supported distribution channel with its enabled flag and derived readiness
    • typestringDistribution channel typeOne of: pickup · shipping · locker
    • enabledbooleanWhether the store has enabled this channel
    • activeCountintegerNumber of active fulfilling entities backing this channel (active locations for pickup, active shipping methods for shipping)
    • blockingReasonstringWhy an enabled channel cannot yet fulfil; null when ready or disabledOne of: no_active_location · no_active_shipping_method · no_active_locker_method
    • settingsobjectOpaque, type-specific channel settings

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/distribution-options
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "channels": [
    {
      "type": "shipping",
      "enabled": true,
      "activeCount": 2,
      "blockingReason": null,
      "settings": {}
    }
  ]
}
read#
PUT/rest/v1/seller/stores/{storeId}/distribution-options/channels/{type}stock:read_writeEnable or configure a distribution channel

Enables a distribution channel for the store and replaces its settings. Idempotent: repeating the call sets the same desired state. Returns the full distribution options after enabling the channel. Requires the `stock:read_write`…

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • typestringrequiredDistribution channel typeOne of: pickup · shipping · locker

Request body · application/json

  • settingsobjectOpaque, type-specific channel settings bag. Distribution stores it as-is.

Response · 200

  • storeIdstring · uuidStore identifier
  • channelsarray<object>Every supported distribution channel with its enabled flag and derived readiness
    • typestringDistribution channel typeOne of: pickup · shipping · locker
    • enabledbooleanWhether the store has enabled this channel
    • activeCountintegerNumber of active fulfilling entities backing this channel (active locations for pickup, active shipping methods for shipping)
    • blockingReasonstringWhy an enabled channel cannot yet fulfil; null when ready or disabledOne of: no_active_location · no_active_shipping_method · no_active_locker_method
    • settingsobjectOpaque, type-specific channel settings

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/distribution-options/channels/pickup
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "settings": {}
}
jsonResponse · 200
{
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "channels": [
    {
      "type": "shipping",
      "enabled": true,
      "activeCount": 2,
      "blockingReason": null,
      "settings": {}
    }
  ]
}
write#
DELETE/rest/v1/seller/stores/{storeId}/distribution-options/channels/{type}stock:read_writeDisable a distribution channel

Disables a distribution channel for the store. Settings are preserved so re-enabling restores them. Returns the full distribution options after disabling. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • typestringrequiredDistribution channel typeOne of: pickup · shipping · locker

Response · 200

  • storeIdstring · uuidStore identifier
  • channelsarray<object>Every supported distribution channel with its enabled flag and derived readiness
    • typestringDistribution channel typeOne of: pickup · shipping · locker
    • enabledbooleanWhether the store has enabled this channel
    • activeCountintegerNumber of active fulfilling entities backing this channel (active locations for pickup, active shipping methods for shipping)
    • blockingReasonstringWhy an enabled channel cannot yet fulfil; null when ready or disabledOne of: no_active_location · no_active_shipping_method · no_active_locker_method
    • settingsobjectOpaque, type-specific channel settings

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/distribution-options/channels/pickup
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "storeId": "01932a00-0000-7000-8000-000000000002",
  "channels": [
    {
      "type": "shipping",
      "enabled": true,
      "activeCount": 2,
      "blockingReason": null,
      "settings": {}
    }
  ]
}
write#

Seller Shipping Methods 10 operations

GET/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}/itemsstock:readGet shipping method item scope

Returns the item scope of a shipping method: whether it applies to all items, and the opaque item references it is scoped to when narrowed. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • methodIdstring · uuidShipping method id
  • appliesToAllbooleanWhen true the method applies to every item and itemIds is empty
  • itemIdsarray<string>Opaque external item references the method is scoped to

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/shipping-methods/01914d0e-5e6f-7071-8283-9e0f10213245/items
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "methodId": "01914d0e-92a3-74b5-86c7-324354657689",
  "appliesToAll": false,
  "itemIds": [
    "item-ref-001",
    "item-ref-002"
  ]
}
read#
PUT/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}/itemsstock:read_writeReplace shipping method item scope

Replaces a shipping method's item scope. Set appliesToAll=true (with an empty itemIds) to apply to every item, or provide a specific set of opaque item references. Duplicate references are deduplicated. An item reference is an opaque host…

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Request body · application/json

  • appliesToAllbooleanWhen true the method applies to every item; itemIds must then be empty
  • itemIdsarray<string>Opaque external item references to scope the method to (max 1000)

Response · 200

  • methodIdstring · uuidShipping method id
  • appliesToAllbooleanWhen true the method applies to every item and itemIds is empty
  • itemIdsarray<string>Opaque external item references the method is scoped to

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/shipping-methods/01914d0e-5e6f-7071-8283-9e0f10213245/items
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "appliesToAll": false,
  "itemIds": [
    "item-ref-001",
    "item-ref-002"
  ]
}
jsonResponse · 200
{
  "methodId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "appliesToAll": false,
  "itemIds": [
    "item-ref-001",
    "item-ref-002"
  ]
}
write#
GET/rest/v1/seller/stores/{storeId}/shipping-methodsstock:readList shipping methods

Returns all shipping methods for the specified store. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequiredShipping method identifier
    • storeIdstring · uuidrequiredParent store identifier
    • namestringrequired
    • isActivebooleanrequired
    • eligibilityobjectrequiredPackage eligibility limits (canonical mm / grams)
    • dimDivisorintegerrequiredDimensional weight divisor
    • freeDeliveryThresholdobjectrequired
    • zonesarray<object>required
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • _metadataobjectrequired
    • countinteger

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/shipping-methods
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "storeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "name": "Standard Delivery",
      "isActive": false,
      "eligibility": {
        "maxWeightGrams": 30000,
        "maxLengthMm": 1200,
        "maxWidthMm": 600,
        "maxHeightMm": 600
      },
      "dimDivisor": 5000,
      "freeDeliveryThreshold": {
        "enabled": false,
        "amountCents": 5000,
        "currency": "EUR"
      },
      "zones": [
        {
          "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
          "name": "Baltic States",
          "countries": [
            "LT",
            "LV",
            "EE"
          ],
          "transitDays": 3,
          "rate": {
            "type": "flat",
            "amountCents": 499,
            "currency": "EUR",
            "brackets": "Brackets"
          },
          "createdAt": "2026-09-10T09:24:11Z",
          "updatedAt": "2026-09-10T09:24:11Z"
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "_metadata": {
    "count": 3
  }
}
read#
POST/rest/v1/seller/stores/{storeId}/shipping-methodsstock:read_writeCreate shipping method

Creates a new shipping method for the specified store. Optionally includes initial zones. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • namestringrequired
  • dimDivisorintegerDimensional weight divisor
  • maxWeightGramsinteger
  • maxLengthMminteger
  • maxWidthMminteger
  • maxHeightMminteger
  • zonesarray<object>Initial zones (optional, for starter flow). Maximum 5 per method.
    • namestringrequired
    • countriesarray<string>requiredCountry codes (ISO 3166-1 alpha-2)
    • rateobjectrequiredThe nested rate object of a shipping zone: { type, amountCents, currency }.
    • transitDaysintegerEstimated transit days
    • weightBracketsarray<object>Weight-tiered brackets (only for weight_tiered rate type)
  • freeDeliveryThresholdobject
    • enabledbooleanrequiredWhether free delivery threshold is enabled
    • amountCentsintegerThreshold amount in cents
    • currencystringCurrency code (ISO 4217)

Response · 201

  • idstring · uuidrequiredShipping method identifier
  • storeIdstring · uuidrequiredParent store identifier
  • namestringrequired
  • isActivebooleanrequired
  • eligibilityobjectrequiredPackage eligibility limits (canonical mm / grams)
    • maxWeightGramsinteger
    • maxLengthMminteger
    • maxWidthMminteger
    • maxHeightMminteger
  • dimDivisorintegerrequiredDimensional weight divisor
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • zonesarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • countriesarray<string>required
    • transitDaysinteger
    • rateobjectrequired
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/shipping-methods
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Standard Delivery",
  "dimDivisor": 5000,
  "maxWeightGrams": 30000,
  "maxLengthMm": 1200,
  "maxWidthMm": 600,
  "maxHeightMm": 600,
  "zones": [
    {
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR"
      },
      "transitDays": 3,
      "weightBrackets": [
        {
          "ceilingGrams": 5000,
          "amountCents": 499,
          "currency": "EUR"
        }
      ]
    }
  ],
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  }
}
jsonResponse · 201
{
  "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "storeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "name": "Standard Delivery",
  "isActive": false,
  "eligibility": {
    "maxWeightGrams": 30000,
    "maxLengthMm": 1200,
    "maxWidthMm": 600,
    "maxHeightMm": 600
  },
  "dimDivisor": 5000,
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "zones": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "transitDays": 3,
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR",
        "brackets": [
          {
            "ceilingGrams": 5000,
            "amountCents": 499
          }
        ]
      },
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}stock:readGet shipping method

Returns a specific shipping method for the authenticated seller. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • idstring · uuidrequiredShipping method identifier
  • storeIdstring · uuidrequiredParent store identifier
  • namestringrequired
  • isActivebooleanrequired
  • eligibilityobjectrequiredPackage eligibility limits (canonical mm / grams)
    • maxWeightGramsinteger
    • maxLengthMminteger
    • maxWidthMminteger
    • maxHeightMminteger
  • dimDivisorintegerrequiredDimensional weight divisor
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • zonesarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • countriesarray<string>required
    • transitDaysinteger
    • rateobjectrequired
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/shipping-methods/01914d0e-a3b4-75c6-97d8-43546576879a
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "storeId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "name": "Standard Delivery",
  "isActive": false,
  "eligibility": {
    "maxWeightGrams": 30000,
    "maxLengthMm": 1200,
    "maxWidthMm": 600,
    "maxHeightMm": 600
  },
  "dimDivisor": 5000,
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "zones": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "transitDays": 3,
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR",
        "brackets": [
          {
            "ceilingGrams": 5000,
            "amountCents": 499
          }
        ]
      },
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
PUT/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}stock:read_writeChange shipping method

Changes shipping method settings including name, eligibility limits, dimensional divisor, and free delivery threshold. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Request body · application/json

  • namestringrequired
  • dimDivisorintegerrequiredDimensional weight divisor
  • maxWeightGramsinteger
  • maxLengthMminteger
  • maxWidthMminteger
  • maxHeightMminteger
  • freeDeliveryThresholdobject
    • enabledbooleanrequiredWhether free delivery threshold is enabled
    • amountCentsintegerThreshold amount in cents
    • currencystringCurrency code (ISO 4217)

Response · 200

  • idstring · uuidrequiredShipping method identifier
  • storeIdstring · uuidrequiredParent store identifier
  • namestringrequired
  • isActivebooleanrequired
  • eligibilityobjectrequiredPackage eligibility limits (canonical mm / grams)
    • maxWeightGramsinteger
    • maxLengthMminteger
    • maxWidthMminteger
    • maxHeightMminteger
  • dimDivisorintegerrequiredDimensional weight divisor
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • zonesarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • countriesarray<string>required
    • transitDaysinteger
    • rateobjectrequired
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/shipping-methods/01914d0e-a3b4-75c6-97d8-43546576879a
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Express Delivery",
  "dimDivisor": 5000,
  "maxWeightGrams": 30000,
  "maxLengthMm": 1200,
  "maxWidthMm": 600,
  "maxHeightMm": 600,
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  }
}
jsonResponse · 200
{
  "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "storeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "name": "Standard Delivery",
  "isActive": false,
  "eligibility": {
    "maxWeightGrams": 30000,
    "maxLengthMm": 1200,
    "maxWidthMm": 600,
    "maxHeightMm": 600
  },
  "dimDivisor": 5000,
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "zones": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "transitDays": 3,
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR",
        "brackets": [
          {
            "ceilingGrams": 5000,
            "amountCents": 499
          }
        ]
      },
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
DELETE/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}stock:read_writeRemove shipping method

Removes a shipping method. Refused for an active shipping method with a rated zone while no other such method remains, even when pickup or lockers stay active. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/shipping-methods/01914d0e-a3b4-75c6-97d8-43546576879a
Authorization: Bearer $TOKEN
write#
POST/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}/activatestock:read_writeActivate shipping method

Activates a deactivated shipping method, making it available for checkout. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • idstring · uuidrequiredShipping method identifier
  • storeIdstring · uuidrequiredParent store identifier
  • namestringrequired
  • isActivebooleanrequired
  • eligibilityobjectrequiredPackage eligibility limits (canonical mm / grams)
    • maxWeightGramsinteger
    • maxLengthMminteger
    • maxWidthMminteger
    • maxHeightMminteger
  • dimDivisorintegerrequiredDimensional weight divisor
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • zonesarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • countriesarray<string>required
    • transitDaysinteger
    • rateobjectrequired
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/shipping-methods/01914d0e-8192-73a4-b5b6-213243546578/activate
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "storeId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "name": "Standard Delivery",
  "isActive": false,
  "eligibility": {
    "maxWeightGrams": 30000,
    "maxLengthMm": 1200,
    "maxWidthMm": 600,
    "maxHeightMm": 600
  },
  "dimDivisor": 5000,
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "zones": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "transitDays": 3,
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR",
        "brackets": [
          {
            "ceilingGrams": 5000,
            "amountCents": 499
          }
        ]
      },
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}/deactivatestock:read_writeDeactivate shipping method

Deactivates an active shipping method. Refused when the store would keep no active delivery option: no other active shipping method with a rated zone, active pickup location or active locker method. Requires the `stock:read_write`…

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • idstring · uuidrequiredShipping method identifier
  • storeIdstring · uuidrequiredParent store identifier
  • namestringrequired
  • isActivebooleanrequired
  • eligibilityobjectrequiredPackage eligibility limits (canonical mm / grams)
    • maxWeightGramsinteger
    • maxLengthMminteger
    • maxWidthMminteger
    • maxHeightMminteger
  • dimDivisorintegerrequiredDimensional weight divisor
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • zonesarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • countriesarray<string>required
    • transitDaysinteger
    • rateobjectrequired
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/shipping-methods/01914d0e-7081-7293-a4a5-102132435467/deactivate
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "storeId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "name": "Standard Delivery",
  "isActive": false,
  "eligibility": {
    "maxWeightGrams": 30000,
    "maxLengthMm": 1200,
    "maxWidthMm": 600,
    "maxHeightMm": 600
  },
  "dimDivisor": 5000,
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "zones": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "transitDays": 3,
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR",
        "brackets": [
          {
            "ceilingGrams": 5000,
            "amountCents": 499
          }
        ]
      },
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PUT/rest/v1/seller/stores/{storeId}/shipping-methods/{methodId}/zonesstock:read_writeReplace shipping method zones

Replaces all zones for a shipping method. Existing zones are removed and replaced with the provided set. An active shipping method must keep at least one zone: an empty set is refused with 422 `/errors/publish-precondition-failed`, field…

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Request body · application/json

  • zonesarray<object>requiredReplacement zones. Maximum 5 per method.
    • namestringrequired
    • countriesarray<string>requiredCountry codes (ISO 3166-1 alpha-2)
    • rateobjectrequiredThe nested rate object of a shipping zone: { type, amountCents, currency }.
    • transitDaysintegerEstimated transit days
    • weightBracketsarray<object>Weight-tiered brackets (only for weight_tiered rate type)

Response · 200

  • idstring · uuidrequiredShipping method identifier
  • storeIdstring · uuidrequiredParent store identifier
  • namestringrequired
  • isActivebooleanrequired
  • eligibilityobjectrequiredPackage eligibility limits (canonical mm / grams)
    • maxWeightGramsinteger
    • maxLengthMminteger
    • maxWidthMminteger
    • maxHeightMminteger
  • dimDivisorintegerrequiredDimensional weight divisor
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • zonesarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • countriesarray<string>required
    • transitDaysinteger
    • rateobjectrequired
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/shipping-methods/01914d0e-a3b4-75c6-97d8-43546576879a/zones
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "zones": [
    {
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR"
      },
      "transitDays": 3,
      "weightBrackets": [
        {
          "ceilingGrams": 5000,
          "amountCents": 499,
          "currency": "EUR"
        }
      ]
    }
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-8192-73a4-b5b6-213243546578",
  "storeId": "01914d0e-7081-7293-a4a5-102132435467",
  "name": "Standard Delivery",
  "isActive": false,
  "eligibility": {
    "maxWeightGrams": 30000,
    "maxLengthMm": 1200,
    "maxWidthMm": 600,
    "maxHeightMm": 600
  },
  "dimDivisor": 5000,
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "zones": [
    {
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "name": "Baltic States",
      "countries": [
        "LT",
        "LV",
        "EE"
      ],
      "transitDays": 3,
      "rate": {
        "type": "flat",
        "amountCents": 499,
        "currency": "EUR",
        "brackets": [
          {
            "ceilingGrams": 5000,
            "amountCents": 499
          }
        ]
      },
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#

Seller Locker Methods 9 operations

GET/rest/v1/seller/stores/{storeId}/locker-methodsstock:readList locker methods

Returns all locker methods for the specified store. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequiredLocker method identifier
    • carrierNetworkCodestringrequired
    • carrierNetworkNamestringrequired
    • isActivebooleanrequired
    • priceobjectrequiredFlat buyer price
    • freeDeliveryThresholdobjectrequired
    • countriesarray<object>requiredPer-country transit schedule
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
  • _metadataobjectrequired
    • countinteger

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/locker-methods
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "carrierNetworkCode": "omniva",
      "carrierNetworkName": "Omniva",
      "isActive": false,
      "price": {
        "amountCents": 299,
        "currency": "EUR"
      },
      "freeDeliveryThreshold": {
        "enabled": false,
        "amountCents": 5000,
        "currency": "EUR"
      },
      "countries": [
        {
          "countryCode": "LT",
          "transitDays": 1
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "_metadata": {
    "count": 2
  }
}
read#
POST/rest/v1/seller/stores/{storeId}/locker-methodsstock:read_writeAdd locker method

Adds a locker method to the store for a single carrier network. Born active. The network is immutable -- switching networks is delete + add. One method per network per store. Returns 422 while the carrier network has no configured terminal…

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • carrierNetworkCodestringrequiredCarrier network code (immutable after creation)
  • priceobjectrequired
    • amountCentsintegerrequiredFlat buyer price in cents
    • currencystringrequiredCurrency code (ISO 4217)
  • countriesarray<object>requiredPer-country transit schedule (at least one destination, max 60)
    • countryCodestringrequiredISO 3166-1 alpha-2 destination country code
    • transitDaysintegerrequiredTransit days to the destination (0-30)
  • freeDeliveryThresholdobject
    • enabledbooleanrequired
    • amountCentsintegerThreshold amount in cents
    • currencystringCurrency code (ISO 4217)

Response · 201

  • idstring · uuidrequiredLocker method identifier
  • carrierNetworkCodestringrequired
  • carrierNetworkNamestringrequired
  • isActivebooleanrequired
  • priceobjectrequiredFlat buyer price
    • amountCentsinteger
    • currencystring
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • countriesarray<object>requiredPer-country transit schedule
    • countryCodestring
    • transitDaysinteger
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/locker-methods
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "carrierNetworkCode": "omniva",
  "price": {
    "amountCents": 299,
    "currency": "EUR"
  },
  "countries": [
    {
      "countryCode": "LT",
      "transitDays": 1
    }
  ],
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  }
}
jsonResponse · 201
{
  "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "carrierNetworkCode": "omniva",
  "carrierNetworkName": "Omniva",
  "isActive": false,
  "price": {
    "amountCents": 299,
    "currency": "EUR"
  },
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "countries": [
    {
      "countryCode": "LT",
      "transitDays": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/locker-methods/{methodId}stock:readGet locker method

Returns a single locker method. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • idstring · uuidrequiredLocker method identifier
  • carrierNetworkCodestringrequired
  • carrierNetworkNamestringrequired
  • isActivebooleanrequired
  • priceobjectrequiredFlat buyer price
    • amountCentsinteger
    • currencystring
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • countriesarray<object>requiredPer-country transit schedule
    • countryCodestring
    • transitDaysinteger
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/locker-methods/01914d0e-c5d6-77e8-b9fa-6576879aabbc
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "carrierNetworkCode": "omniva",
  "carrierNetworkName": "Omniva",
  "isActive": false,
  "price": {
    "amountCents": 299,
    "currency": "EUR"
  },
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "countries": [
    {
      "countryCode": "LT",
      "transitDays": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
PUT/rest/v1/seller/stores/{storeId}/locker-methods/{methodId}stock:read_writeChange locker method

Changes a locker method's price, free-delivery threshold, and country transit schedule. The carrier network is immutable -- switching networks is delete + add. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Request body · application/json

  • priceobjectrequired
    • amountCentsintegerrequiredFlat buyer price in cents
    • currencystringrequiredCurrency code (ISO 4217)
  • countriesarray<object>requiredPer-country transit schedule (at least one destination, max 60)
    • countryCodestringrequiredISO 3166-1 alpha-2 destination country code
    • transitDaysintegerrequiredTransit days to the destination (0-30)
  • freeDeliveryThresholdobject
    • enabledbooleanrequired
    • amountCentsintegerThreshold amount in cents
    • currencystringCurrency code (ISO 4217)

Response · 200

  • idstring · uuidrequiredLocker method identifier
  • carrierNetworkCodestringrequired
  • carrierNetworkNamestringrequired
  • isActivebooleanrequired
  • priceobjectrequiredFlat buyer price
    • amountCentsinteger
    • currencystring
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • countriesarray<object>requiredPer-country transit schedule
    • countryCodestring
    • transitDaysinteger
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/locker-methods/01914d0e-c5d6-77e8-b9fa-6576879aabbc
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "price": {
    "amountCents": 299,
    "currency": "EUR"
  },
  "countries": [
    {
      "countryCode": "LT",
      "transitDays": 1
    }
  ],
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  }
}
jsonResponse · 200
{
  "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "carrierNetworkCode": "omniva",
  "carrierNetworkName": "Omniva",
  "isActive": false,
  "price": {
    "amountCents": 299,
    "currency": "EUR"
  },
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "countries": [
    {
      "countryCode": "LT",
      "transitDays": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
DELETE/rest/v1/seller/stores/{storeId}/locker-methods/{methodId}stock:read_writeRemove locker method

Removes a locker method and clears its per-item assignments. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/locker-methods/01914d0e-c5d6-77e8-b9fa-6576879aabbc
Authorization: Bearer $TOKEN
write#
POST/rest/v1/seller/stores/{storeId}/locker-methods/{methodId}/pausestock:read_writePause locker method

Pauses a locker method -- it stops being offered at checkout until resumed. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • idstring · uuidrequiredLocker method identifier
  • carrierNetworkCodestringrequired
  • carrierNetworkNamestringrequired
  • isActivebooleanrequired
  • priceobjectrequiredFlat buyer price
    • amountCentsinteger
    • currencystring
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • countriesarray<object>requiredPer-country transit schedule
    • countryCodestring
    • transitDaysinteger
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/locker-methods/01914d0e-5e6f-7071-8283-9e0f10213245/pause
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "carrierNetworkCode": "omniva",
  "carrierNetworkName": "Omniva",
  "isActive": false,
  "price": {
    "amountCents": 299,
    "currency": "EUR"
  },
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "countries": [
    {
      "countryCode": "LT",
      "transitDays": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/locker-methods/{methodId}/resumestock:read_writeResume locker method

Resumes a paused locker method -- it is offered at checkout again. Returns 422 while the carrier network has no configured terminal feed. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • idstring · uuidrequiredLocker method identifier
  • carrierNetworkCodestringrequired
  • carrierNetworkNamestringrequired
  • isActivebooleanrequired
  • priceobjectrequiredFlat buyer price
    • amountCentsinteger
    • currencystring
  • freeDeliveryThresholdobjectrequired
    • enabledboolean
    • amountCentsinteger
    • currencystring
  • countriesarray<object>requiredPer-country transit schedule
    • countryCodestring
    • transitDaysinteger
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/locker-methods/01914d0e-8192-73a4-b5b6-213243546578/resume
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "carrierNetworkCode": "omniva",
  "carrierNetworkName": "Omniva",
  "isActive": false,
  "price": {
    "amountCents": 299,
    "currency": "EUR"
  },
  "freeDeliveryThreshold": {
    "enabled": false,
    "amountCents": 5000,
    "currency": "EUR"
  },
  "countries": [
    {
      "countryCode": "LT",
      "transitDays": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/locker-methods/{methodId}/itemsstock:readGet locker method item scope

Returns the item scope of a locker method: the opaque item references it is scoped to. Requires the `stock:read` capability (the Stock area at read level).

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Response · 200

  • methodIdstring · uuidrequiredLocker method id
  • itemIdsarray<string>requiredOpaque external item references the method is scoped to

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/locker-methods/01914d0e-7081-7293-a4a5-102132435467/items
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "methodId": "01914d0e-7081-7293-a4a5-102132435467",
  "itemIds": [
    "Item ids"
  ]
}
read#
PUT/rest/v1/seller/stores/{storeId}/locker-methods/{methodId}/itemsstock:read_writeReplace locker method item scope

Replaces a locker method's item scope with exactly the supplied opaque item references. Duplicate references are deduplicated; an empty list clears the method. Requires the `stock:read_write` capability (the Stock area at read-write level).

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • methodIdstring · uuidrequired

Request body · application/json

  • itemIdsarray<string>Opaque external item references to scope the method to

Response · 200

  • methodIdstring · uuidrequiredLocker method id
  • itemIdsarray<string>requiredOpaque external item references the method is scoped to

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/locker-methods/01914d0e-7081-7293-a4a5-102132435467/items
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "itemIds": [
    "Item ids"
  ]
}
jsonResponse · 200
{
  "methodId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "itemIds": [
    "Item ids"
  ]
}
write#

Seller Item Distribution 2 operations

GET/rest/v1/seller/stores/{storeId}/items/{itemId}/distributionstock:readGet the distribution of an item

Returns the full distribution of a single opaque item: the store shipping methods that deliver it and the pickup locations that stock it. Shipping methods with no item scope apply to all items; pickup is strict opt-in, so pickup locations…

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired
  • itemIdstringrequiredOpaque external item reference

Response · 200

  • itemIdstringOpaque external item reference, echoed back as supplied
  • shippingMethodsarray<object>Shipping methods that deliver the item
    • idstring · uuid
    • namestring
    • isActiveboolean
    • appliesToAllbooleanWhether this method reaches the item because it applies to all items
  • pickupLocationsarray<object>Pickup locations that stock the item (strict opt-in: appliesToAll is always false)
    • idstring · uuid
    • namestring
    • isActiveboolean
    • appliesToAllbooleanAlways false — pickup is strict opt-in, so a location only ever stocks items it has an explicit row for. There is no "applies to all items" pickup default.
  • lockerMethodsarray<object>Locker methods that carry the item (strict opt-in: appliesToAll is always false)
    • idstring · uuid
    • carrierNetworkCodestring
    • carrierNetworkNamestring
    • isActiveboolean
    • appliesToAllbooleanAlways false — locker delivery is strict opt-in, so a locker method only ever carries items it has an explicit row for.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/items/Item id/distribution
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "itemId": "item-ref-001",
  "shippingMethods": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "name": "Standard Delivery",
      "isActive": true,
      "appliesToAll": false
    }
  ],
  "pickupLocations": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "name": "Main Office",
      "isActive": true,
      "appliesToAll": false
    }
  ],
  "lockerMethods": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "carrierNetworkCode": "omniva",
      "carrierNetworkName": "Omniva",
      "isActive": true,
      "appliesToAll": false
    }
  ]
}
read#
PUT/rest/v1/seller/stores/{storeId}/items/{itemId}/distributionstock:read_writeSet the distribution of an item

Sets, in one gesture, the full distribution of a single opaque item: which of the store's shipping methods deliver it and which of its pickup locations stock it. Each list is reconciled independently against its channel; selected channels…

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • itemIdstringrequiredOpaque external item reference

Request body · application/json

  • shippingMethodIdsarray<string>Store shipping method ids that should deliver the item (max 1000)
  • pickupLocationIdsarray<string>Store pickup location ids that should stock the item (max 1000)
  • lockerMethodIdsarray<string>Store locker method ids that should carry the item (max 1000)

Response · 200

  • itemIdstringOpaque external item reference, echoed back as supplied
  • shippingMethodsarray<object>Shipping methods that deliver the item
    • idstring · uuid
    • namestring
    • isActiveboolean
    • appliesToAllbooleanWhether this method reaches the item because it applies to all items
  • pickupLocationsarray<object>Pickup locations that stock the item (strict opt-in: appliesToAll is always false)
    • idstring · uuid
    • namestring
    • isActiveboolean
    • appliesToAllbooleanAlways false — pickup is strict opt-in, so a location only ever stocks items it has an explicit row for. There is no "applies to all items" pickup default.
  • lockerMethodsarray<object>Locker methods that carry the item (strict opt-in: appliesToAll is always false)
    • idstring · uuid
    • carrierNetworkCodestring
    • carrierNetworkNamestring
    • isActiveboolean
    • appliesToAllbooleanAlways false — locker delivery is strict opt-in, so a locker method only ever carries items it has an explicit row for.

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/items/Item id/distribution
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "shippingMethodIds": [
    "01932a00-0000-7000-8000-000000000010"
  ],
  "pickupLocationIds": [
    "01932a00-0000-7000-8000-000000000020"
  ],
  "lockerMethodIds": [
    "01932a00-0000-7000-8000-000000000030"
  ]
}
jsonResponse · 200
{
  "itemId": "item-ref-001",
  "shippingMethods": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "name": "Standard Delivery",
      "isActive": true,
      "appliesToAll": false
    }
  ],
  "pickupLocations": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "name": "Main Office",
      "isActive": true,
      "appliesToAll": false
    }
  ],
  "lockerMethods": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "carrierNetworkCode": "omniva",
      "carrierNetworkName": "Omniva",
      "isActive": true,
      "appliesToAll": false
    }
  ]
}
write#

Seller Carrier Networks 1 operation

GET/rest/v1/seller/carrier-networksauthenticatedList carrier networks (seller)

Lists the enabled carrier networks -- code, name, coverage, read-only size classes and whether the terminal directory is configured. Backs the "add locker network" picker and the mark-shipped carrier select. A network with…

Requires

authenticated

Response · 200

  • itemsarray<object>required
    • codestringrequired
    • namestringrequired
    • countryCoveragearray<string>required
    • sizeClassesarray<object>required
    • terminalDirectoryConfiguredbooleanrequiredWhether the terminal directory feed of this network is configured. While false, the network cannot be added or resumed as a locker method, but it stays listed for the mark-shipped carrier select.

Errors

401 · 500 — See the error reference

httpRequest
GET /rest/v1/seller/carrier-networks
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "code": "omniva",
      "name": "Omniva",
      "countryCoverage": [
        "LT",
        "LV",
        "EE"
      ],
      "sizeClasses": [
        {
          "id": "Id",
          "label": "M",
          "maxLengthMm": 380,
          "maxWidthMm": 640,
          "maxHeightMm": 190,
          "maxWeightGrams": 30000
        }
      ],
      "terminalDirectoryConfigured": true
    }
  ]
}
read#

Seller Listings 10 operations

POST/rest/v1/seller/stores/{storeId}/listingsproducts:read_writeCreate listing

Creates a new listing with a default variant for the authenticated seller. Answers 503 with `type` `/errors/file-storage-unavailable` when file storage cannot be reached; retry. Requires the `products:read_write` capability (the Products…

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • titlestringrequiredListing title
  • descriptionstringListing description
  • categoryIdstring · uuidCategory ID
  • brandIdstring · uuidSeller-chosen brand (governed Brand id). Optional.
  • sourcestringrequiredListing sourceOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether to track inventory for this listing
  • optionsarray<object>Listing options (e.g. Color, Size). Max 3.
    • namestringOption name (e.g. Color, Size)
    • valuesarray<string>List of option values
  • variantsarray<object>Listing variants with pricing, SKU, barcodes, and media. Max 100.
    • optionValuesobjectMap of option name to selected value (keys must match defined option names)
    • priceAmountintegerPrice amount in cents
    • priceCurrencystringPrice currency (ISO 4217)
    • skustringSKU identifier
    • barcodesarray<object>Barcodes for this variant
    • descriptiveAttributesarray<object>Descriptive attribute values for this variant
    • mediaUploadIdsarray<string>Upload IDs for variant media (from POST /rest/v1/uploads)
  • attributesarray<object>Listing-level attribute values. Max 20.
    • attributeIdstring · uuidrequiredAttribute identifier
    • attributeValueIdstring · uuidrequiredAttribute value identifier
  • mediaUploadIdsarray<string>Upload IDs for listing-level media (from POST /rest/v1/uploads). Max 20.

Response · 201

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-chosen brand (governed Brand id). Optional.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • variantsarray<object>
    • idstring · uuid
    • isDefaultboolean
    • skustring
    • variantSignaturestring
    • statusstringOne of: draft · active · inactive · out_of_stock · archived
    • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
    • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
    • priceCurrencystring
    • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • barcodesarray<object>
    • mediaarray<object>
    • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • attributeValuesarray<object>
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • optionsarray<object>
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • mediaarray<object>Listing-level media, shared across all variants, ordered by position ascending.
    • idstring · uuid
    • urlstring · uriPublic URL resolved from the stored media path.
    • altTextstring
    • positioninteger
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/listings
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "categoryId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "brandId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "source": "manual",
  "inventoryTracked": true,
  "options": [
    {
      "name": "Color",
      "values": [
        "Red"
      ]
    }
  ],
  "variants": [
    {
      "optionValues": {
        "Color": "Red",
        "Size": "M"
      },
      "priceAmount": 2999,
      "priceCurrency": "EUR",
      "sku": "WBH-RED-M",
      "barcodes": [
        {
          "type": "ean13",
          "value": "5901234123457"
        }
      ],
      "descriptiveAttributes": [
        {
          "attributeId": "01914d0e-6f70-7182-9394-0f1021324356",
          "attributeValueId": "01914d0e-92a3-74b5-86c7-324354657689"
        }
      ],
      "mediaUploadIds": [
        "Media upload ids"
      ]
    }
  ],
  "attributes": [
    {
      "attributeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "attributeValueId": "01914d0e-7081-7293-a4a5-102132435467"
    }
  ],
  "mediaUploadIds": [
    "Media upload ids"
  ]
}
jsonResponse · 201
{
  "id": "01914d0e-6f70-7182-9394-0f1021324356",
  "storeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "userId": "User id",
  "categoryId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "brandId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "variants": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "isDefault": false,
      "sku": "Sku",
      "variantSignature": "Variant signature",
      "status": "draft",
      "publicationStatus": "not_published",
      "priceAmount": 2999,
      "priceCurrency": "EUR",
      "activeSale": {
        "promotionId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
        "name": "Name",
        "salePrice": 129900,
        "frozenReference": 0,
        "regularPrice": 129900,
        "discountVisible": false,
        "state": "live",
        "saleEndsAt": "2026-09-10T09:24:11Z"
      },
      "barcodes": [
        {
          "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
          "barcode": "Barcode",
          "type": "ean8"
        }
      ],
      "media": [
        {
          "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
          "url": "https://storage.example.com/listing-photos/abc123.jpg",
          "position": 1,
          "altText": "Alt text"
        }
      ],
      "optionValues": [
        {
          "optionId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
          "optionValueId": "01914d0e-b4c5-76d7-a8e9-546576879aab"
        }
      ],
      "options": [
        {
          "id": "01914d0e-6f70-7182-9394-0f1021324356",
          "name": "Name",
          "position": 0,
          "values": [
            {}
          ]
        }
      ],
      "attributeValues": [
        {
          "id": "01914d0e-6f70-7182-9394-0f1021324356",
          "attributeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "attributeValueId": "01914d0e-92a3-74b5-86c7-324354657689"
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "attributeId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "attributeValueId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01"
    }
  ],
  "options": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "media": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "url": "https://api.example.com",
      "altText": "Alt text",
      "position": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/listingsproducts:readList listings for a store

Returns a paginated list of listings for a store with optional search, filters, and sorting. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • afterstring · uuidCursor for forward pagination (UUID of last item on previous page)
  • beforestring · uuidCursor for backward pagination (UUID of first item on previous page)
  • limitintegerNumber of items per page
  • includeTotalCountbooleanInclude total count in response metadata
  • statusstringOne of: active · inactive · archived · draft · all
  • publicationStatusstringOne of: all · has_published · has_under_review · has_rejected · has_hidden · no_published
  • categoryIdstring · uuid
  • searchstringCase-insensitive search on title, variant SKU, or variant barcode
  • sortBystringOne of: createdAt · updatedAt · title
  • sortDirstringOne of: asc · desc

Response · 200

  • itemsarray<object>
    • idstring · uuid
    • titlestring
    • categoryIdstring · uuid
    • statusstringOne of: draft · active · inactive · archived
    • sourcestringOne of: manual · csv_import · cms_sync
    • inventoryTrackedboolean
    • variantCountinteger
    • activeVariantCountinteger
    • priceRollupobjectSale-aware price rollup — successor to the old flat `priceRange` (M7). `effectiveMin`/ `effectiveMax` reflect live sale prices; `uniform` is the single struck pair only when every variant shares one sale price and one frozen reference…
    • primaryPhotoUrlstring
    • publicationStatusRollupstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/listings
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "title": "Organic Cotton T-Shirt",
      "categoryId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "status": "draft",
      "source": "manual",
      "inventoryTracked": true,
      "variantCount": 3,
      "activeVariantCount": 2,
      "priceRollup": {
        "currency": "EUR",
        "effectiveMin": 1599,
        "effectiveMax": 2999,
        "variantCount": 5,
        "onSaleVariantCount": 2,
        "uniform": {
          "salePrice": 1599,
          "frozenReference": 1999
        }
      },
      "primaryPhotoUrl": "Primary photo url",
      "publicationStatusRollup": "not_published",
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-6f70-7182-9394-0f1021324356",
    "prevCursor": "01914d0e-6f70-7182-9394-0f1021324356",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/seller/stores/{storeId}/listings/statsproducts:readGet listing stats for a store

Returns aggregate statistics for all listings in a store. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • totalinteger
  • byStatusobject
    • activeinteger
    • inactiveinteger
    • draftinteger
    • archivedinteger
  • totalVariantsinteger
  • publishedVariantsinteger
  • activeOnMarketplaceListingsintegerListings the list returns for status=active and publicationStatus=has_published.
  • underReviewListingsintegerListings the list returns for publicationStatus=has_under_review.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/listings/stats
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "total": 42,
  "byStatus": {
    "active": 30,
    "inactive": 8,
    "draft": 2,
    "archived": 2
  },
  "totalVariants": 120,
  "publishedVariants": 85,
  "activeOnMarketplaceListings": 25,
  "underReviewListings": 3
}
read#
GET/rest/v1/seller/stores/{storeId}/listings/{listingId}products:readGet listing detail

Returns a specific listing with all variants, options, and attribute values for the authenticated seller. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-chosen brand (governed Brand id). Optional.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • variantsarray<object>
    • idstring · uuid
    • isDefaultboolean
    • skustring
    • variantSignaturestring
    • statusstringOne of: draft · active · inactive · out_of_stock · archived
    • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
    • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
    • priceCurrencystring
    • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • barcodesarray<object>
    • mediaarray<object>
    • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • attributeValuesarray<object>
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • optionsarray<object>
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • mediaarray<object>Listing-level media, shared across all variants, ordered by position ascending.
    • idstring · uuid
    • urlstring · uriPublic URL resolved from the stored media path.
    • altTextstring
    • positioninteger
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/listings/01914d0e-6f70-7182-9394-0f1021324356
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-6f70-7182-9394-0f1021324356",
  "storeId": "01914d0e-92a3-74b5-86c7-324354657689",
  "userId": "User id",
  "categoryId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "brandId": "01914d0e-92a3-74b5-86c7-324354657689",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "variants": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "isDefault": false,
      "sku": "Sku",
      "variantSignature": "Variant signature",
      "status": "draft",
      "publicationStatus": "not_published",
      "priceAmount": 2999,
      "priceCurrency": "EUR",
      "activeSale": {
        "promotionId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
        "name": "Name",
        "salePrice": 129900,
        "frozenReference": 0,
        "regularPrice": 129900,
        "discountVisible": false,
        "state": "live",
        "saleEndsAt": "2026-09-10T09:24:11Z"
      },
      "barcodes": [
        {
          "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
          "barcode": "Barcode",
          "type": "ean8"
        }
      ],
      "media": [
        {
          "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
          "url": "https://storage.example.com/listing-photos/abc123.jpg",
          "position": 1,
          "altText": "Alt text"
        }
      ],
      "optionValues": [
        {
          "optionId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "optionValueId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023"
        }
      ],
      "options": [
        {
          "id": "01914d0e-6f70-7182-9394-0f1021324356",
          "name": "Name",
          "position": 0,
          "values": [
            {}
          ]
        }
      ],
      "attributeValues": [
        {
          "id": "01914d0e-6f70-7182-9394-0f1021324356",
          "attributeId": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "attributeValueId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01"
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "attributeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "attributeValueId": "01914d0e-5e6f-7071-8283-9e0f10213245"
    }
  ],
  "options": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "media": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "url": "https://api.example.com",
      "altText": "Alt text",
      "position": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/titleproducts:read_writeUpdate listing title

Updates the title of an existing listing. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • titlestringrequiredListing title

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-declared brand id (opaque cross-service reference), or null when unset.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/listings/01914d0e-92a3-74b5-86c7-324354657689/title
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "title": "Wireless Bluetooth Headphones"
}
jsonResponse · 200
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "storeId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "userId": "User id",
  "categoryId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "brandId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/descriptionproducts:read_writeUpdate listing description

Updates the description of an existing listing. Send null to clear the description. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • descriptionstringListing description (null to clear)

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-declared brand id (opaque cross-service reference), or null when unset.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/listings/01914d0e-5e6f-7071-8283-9e0f10213245/description
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "description": "Description"
}
jsonResponse · 200
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "storeId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "userId": "User id",
  "categoryId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "brandId": "01914d0e-8192-73a4-b5b6-213243546578",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/categoryproducts:read_writeUpdate listing category

Updates the category of an existing listing. Send null to unset the category. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • categoryIdstring · uuidCategory ID (null to unset)

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-declared brand id (opaque cross-service reference), or null when unset.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/listings/01914d0e-92a3-74b5-86c7-324354657689/category
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "categoryId": "01914d0e-4d5e-7f60-b172-8d9e0f102134"
}
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "storeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "userId": "User id",
  "categoryId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "brandId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/brandproducts:read_writeUpdate listing brand

Sets or clears the seller-declared brand of an existing listing. Send null to clear the brand. The brand id is an opaque cross-service reference to a governed Brand (svc-marketplace) — validated for UUID shape only and stored as-is, never…

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • brandIdstring · uuidSeller-chosen brand id (governed Brand from the catalog). Send null to clear the brand. Opaque cross-service reference — validated for UUID shape only, never verified against the catalog.

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-declared brand id (opaque cross-service reference), or null when unset.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/listings/01914d0e-c5d6-77e8-b9fa-6576879aabbc/brand
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "brandId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12"
}
jsonResponse · 200
{
  "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "storeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "userId": "User id",
  "categoryId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "brandId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/product-attributesproducts:read_writeUpdate listing product attributes

Replaces all product attribute values on an existing listing. Sends an empty array to clear all attribute values. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • attributeValuesarray<object>requiredList of attribute value assignments (replaces all existing)
    • attributeIdstring · uuidrequiredAttribute identifier
    • attributeValueIdstring · uuidrequiredAttribute value identifier

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-declared brand id (opaque cross-service reference), or null when unset.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/listings/01914d0e-8192-73a4-b5b6-213243546578/product-attributes
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "attributeValues": [
    {
      "attributeId": "01914d0e-7081-7293-a4a5-102132435467",
      "attributeValueId": "01914d0e-6f70-7182-9394-0f1021324356"
    }
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-6f70-7182-9394-0f1021324356",
  "storeId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "userId": "User id",
  "categoryId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "brandId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PUT/rest/v1/seller/stores/{storeId}/listings/{listingId}/inventory-trackingproducts:read_writeChange listing inventory tracking

Changes inventory tracking for an existing listing. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • inventoryTrackedbooleanrequiredWhether to track inventory for this listing

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring
  • categoryIdstring · uuid
  • brandIdstring · uuidSeller-chosen brand (governed Brand id). Optional.
  • titlestring
  • descriptionstring
  • statusstringOne of: draft · active · inactive · archived
  • sourcestringOne of: manual · csv_import · cms_sync
  • inventoryTrackedbooleanWhether stock is tracked for this listing.
  • defaultVariantIdstring · uuid
  • variantsarray<object>
    • idstring · uuid
    • isDefaultboolean
    • skustring
    • variantSignaturestring
    • statusstringOne of: draft · active · inactive · out_of_stock · archived
    • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
    • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
    • priceCurrencystring
    • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • barcodesarray<object>
    • mediaarray<object>
    • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • attributeValuesarray<object>
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • optionsarray<object>
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • mediaarray<object>Listing-level media, shared across all variants, ordered by position ascending.
    • idstring · uuid
    • urlstring · uriPublic URL resolved from the stored media path.
    • altTextstring
    • positioninteger
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/listings/01914d0e-b4c5-76d7-a8e9-546576879aab/inventory-tracking
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "inventoryTracked": true
}
jsonResponse · 200
{
  "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "storeId": "01914d0e-7081-7293-a4a5-102132435467",
  "userId": "User id",
  "categoryId": "01914d0e-8192-73a4-b5b6-213243546578",
  "brandId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "title": "Wireless Bluetooth Headphones",
  "description": "Description",
  "status": "draft",
  "source": "manual",
  "inventoryTracked": true,
  "defaultVariantId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "variants": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "isDefault": false,
      "sku": "Sku",
      "variantSignature": "Variant signature",
      "status": "draft",
      "publicationStatus": "not_published",
      "priceAmount": 2999,
      "priceCurrency": "EUR",
      "activeSale": {
        "promotionId": "01914d0e-6f70-7182-9394-0f1021324356",
        "name": "Name",
        "salePrice": 129900,
        "frozenReference": 0,
        "regularPrice": 129900,
        "discountVisible": false,
        "state": "live",
        "saleEndsAt": "2026-09-10T09:24:11Z"
      },
      "barcodes": [
        {
          "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
          "barcode": "Barcode",
          "type": "ean8"
        }
      ],
      "media": [
        {
          "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "url": "https://storage.example.com/listing-photos/abc123.jpg",
          "position": 1,
          "altText": "Alt text"
        }
      ],
      "optionValues": [
        {
          "optionId": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "optionValueId": "01914d0e-92a3-74b5-86c7-324354657689"
        }
      ],
      "options": [
        {
          "id": "01914d0e-8192-73a4-b5b6-213243546578",
          "name": "Name",
          "position": 0,
          "values": [
            {}
          ]
        }
      ],
      "attributeValues": [
        {
          "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "attributeId": "01914d0e-8192-73a4-b5b6-213243546578",
          "attributeValueId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023"
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "attributeId": "01914d0e-8192-73a4-b5b6-213243546578",
      "attributeValueId": "01914d0e-7081-7293-a4a5-102132435467"
    }
  ],
  "options": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "media": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "url": "https://api.example.com",
      "altText": "Alt text",
      "position": 1
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#

Seller Listing Media 3 operations

POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/mediaproducts:read_writeAdd listing media

Adds a media item to a listing via a signed upload token (obtained from POST /rest/v1/uploads). Listing-level media is shared across all variants. Answers 503 with `type` `/errors/file-storage-unavailable` when file storage cannot be…

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • uploadIdstringrequiredSigned upload token returned by POST /rest/v1/uploads

Response · 201

  • idstring · uuid
  • urlstring · uriPublic URL resolved from the stored media path.
  • altTextstring
  • positioninteger

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/listings/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/media
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "uploadId": "eyJrIjoi..."
}
jsonResponse · 201
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "url": "https://api.example.com",
  "altText": "Alt text",
  "position": 1
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/media/reorderproducts:read_writeReorder listing media

Reorders the media of a listing. Provide a complete ordered list of all media IDs. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • mediaIdsarray<string>requiredComplete ordered list of all media IDs for this listing

Response · 204

No content.

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/listings/01914d0e-7081-7293-a4a5-102132435467/media/reorder
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "mediaIds": [
    "01914d0e-7081-7293-a4a5-102132435467"
  ]
}
write#
DELETE/rest/v1/seller/stores/{storeId}/listings/{listingId}/media/{mediaId}products:read_writeRemove listing media

Removes a media item from a listing and deletes the stored file. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • mediaIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/listings/01914d0e-92a3-74b5-86c7-324354657689/media/01914d0e-92a3-74b5-86c7-324354657689
Authorization: Bearer $TOKEN
write#

Seller Listing Variants 16 operations

POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variantsproducts:read_writeAdd variant to listing

Adds a new variant to a listing with the specified option value combination. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • optionValueIdsarray<string>requiredList of option value IDs that define this variant combination

Response · 201

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/listings/01914d0e-7081-7293-a4a5-102132435467/variants
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "optionValueIds": [
    "01932a00-0000-7000-8000-000000000010",
    "01932a00-0000-7000-8000-000000000020"
  ]
}
jsonResponse · 201
{
  "id": "01914d0e-7081-7293-a4a5-102132435467",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-5e6f-7071-8283-9e0f10213245",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-7081-7293-a4a5-102132435467",
      "optionValueId": "01914d0e-6f70-7182-9394-0f1021324356"
    }
  ],
  "options": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "attributeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "attributeValueId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}products:readGet listing variant detail

Returns a specific variant of a listing with full detail including barcodes and media. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/listings/01914d0e-4d5e-7f60-b172-8d9e0f102134/variants/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-8192-73a4-b5b6-213243546578",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-6f70-7182-9394-0f1021324356",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-6f70-7182-9394-0f1021324356",
      "optionValueId": "01914d0e-5e6f-7071-8283-9e0f10213245"
    }
  ],
  "options": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "attributeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "attributeValueId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/pricepricing:read_writeUpdate variant price

Updates the base price of a listing variant. Requires the `pricing:read_write` capability (the Pricing area at read-write level).

Requires

pricing:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Request body · application/json

  • amountintegerrequiredPrice amount in minor units (cents)
  • currencystringrequiredISO 4217 currency code

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/listings/01914d0e-6f70-7182-9394-0f1021324356/variants/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/price
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "amount": 7999,
  "currency": "EUR"
}
jsonResponse · 200
{
  "id": "01914d0e-6f70-7182-9394-0f1021324356",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-8192-73a4-b5b6-213243546578",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "optionValueId": "01914d0e-7081-7293-a4a5-102132435467"
    }
  ],
  "options": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "attributeId": "01914d0e-6f70-7182-9394-0f1021324356",
      "attributeValueId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/detailsproducts:read_writeUpdate variant details

Updates SKU and barcodes of a listing variant. Barcodes use replace-all strategy when provided. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Request body · application/json

  • skustringSKU identifier
  • barcodesarray<object>Barcodes (replaces all existing barcodes when provided)
    • typestringrequiredBarcode typeOne of: ean8 · ean13 · gtin12 · isbn13 · internal
    • valuestringrequiredBarcode value

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/listings/01914d0e-7081-7293-a4a5-102132435467/variants/01914d0e-4d5e-7f60-b172-8d9e0f102134/details
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "sku": "ABC-123",
  "barcodes": [
    {
      "type": "ean13",
      "value": "5901234123457"
    }
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "optionValueId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12"
    }
  ],
  "options": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "attributeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "attributeValueId": "01914d0e-4d5e-7f60-b172-8d9e0f102134"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/defining-attributesproducts:read_writeUpdate variant defining attributes

Updates the defining attributes (option values) that form the variant signature. Validates no signature collision with sibling variants. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Request body · application/json

  • optionValuesarray<object>requiredVariant-defining option values that form the variant signature
    • optionIdstring · uuidrequiredOption identifier
    • valueIdstring · uuidrequiredOption value identifier

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/listings/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/variants/01914d0e-8192-73a4-b5b6-213243546578/defining-attributes
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "optionValues": [
    {
      "optionId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "valueId": "01914d0e-8192-73a4-b5b6-213243546578"
    }
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "optionValueId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12"
    }
  ],
  "options": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-92a3-74b5-86c7-324354657689",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "attributeId": "01914d0e-92a3-74b5-86c7-324354657689",
      "attributeValueId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/attributesproducts:read_writeUpdate variant attributes

Replaces all variant-level attribute values for a listing variant. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Request body · application/json

  • attributeValuesarray<object>requiredVariant-level attribute values (replaces all existing values)
    • attributeIdstring · uuidrequiredAttribute identifier
    • attributeValueIdstring · uuidrequiredAttribute value identifier

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/listings/01914d0e-8192-73a4-b5b6-213243546578/variants/01914d0e-7081-7293-a4a5-102132435467/attributes
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "attributeValues": [
    {
      "attributeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "attributeValueId": "01914d0e-a3b4-75c6-97d8-43546576879a"
    }
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-8192-73a4-b5b6-213243546578",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-8192-73a4-b5b6-213243546578",
      "optionValueId": "01914d0e-7081-7293-a4a5-102132435467"
    }
  ],
  "options": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "attributeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "attributeValueId": "01914d0e-92a3-74b5-86c7-324354657689"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/photosproducts:read_writeAdd variant photo

Adds a photo to a listing variant via a signed upload token. Answers 503 with `type` `/errors/file-storage-unavailable` when file storage cannot be reached; retry. Requires the `products:read_write` capability (the Products area at…

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Request body · application/json

  • uploadIdstringrequiredSigned upload token returned by POST /rest/v1/uploads

Response · 201

  • idstring · uuid
  • urlstringPublic URL resolved from the stored media path.
  • positioninteger
  • altTextstring

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/listings/01914d0e-c5d6-77e8-b9fa-6576879aabbc/variants/01914d0e-b4c5-76d7-a8e9-546576879aab/photos
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "uploadId": "eyJrIjoi..."
}
jsonResponse · 201
{
  "id": "01914d0e-8192-73a4-b5b6-213243546578",
  "url": "https://storage.example.com/listing-photos/abc123.jpg",
  "position": 1,
  "altText": "Alt text"
}
write#
DELETE/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/photos/{photoId}products:read_writeDelete variant photo

Removes a photo from a listing variant. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired
  • photoIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/listings/01914d0e-6f70-7182-9394-0f1021324356/variants/01914d0e-5e6f-7071-8283-9e0f10213245/photos/01914d0e-a3b4-75c6-97d8-43546576879a
Authorization: Bearer $TOKEN
write#
PATCH/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/photos/reorderproducts:read_writeReorder variant photos

Reorders the photos of a listing variant. Provide a complete ordered list of all photo IDs. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Request body · application/json

  • photoIdsarray<string>requiredComplete ordered list of all photo IDs for this variant

Response · 204

No content.

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/listings/01914d0e-8192-73a4-b5b6-213243546578/variants/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/photos/reorder
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "photoIds": [
    "01914d0e-a3b4-75c6-97d8-43546576879a"
  ]
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/publishproducts:read_writePublish variant

Submits a variant for publication review. Sets publication status to pending_review. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/listings/01914d0e-4d5e-7f60-b172-8d9e0f102134/variants/01914d0e-b4c5-76d7-a8e9-546576879aab/publish
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-8192-73a4-b5b6-213243546578",
      "optionValueId": "01914d0e-b4c5-76d7-a8e9-546576879aab"
    }
  ],
  "options": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "attributeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "attributeValueId": "01914d0e-5e6f-7071-8283-9e0f10213245"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/unpublishproducts:read_writeUnpublish variant

Unpublishes a variant, removing it from public visibility. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/listings/01914d0e-7081-7293-a4a5-102132435467/variants/01914d0e-c5d6-77e8-b9fa-6576879aabbc/unpublish
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-7081-7293-a4a5-102132435467",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-92a3-74b5-86c7-324354657689",
      "optionValueId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc"
    }
  ],
  "options": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "attributeId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "attributeValueId": "01914d0e-6f70-7182-9394-0f1021324356"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/enableproducts:read_writeEnable variant

Enables a variant, transitioning it to active status. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/listings/01914d0e-a3b4-75c6-97d8-43546576879a/variants/01914d0e-92a3-74b5-86c7-324354657689/enable
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-8192-73a4-b5b6-213243546578",
      "optionValueId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023"
    }
  ],
  "options": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "attributeId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "attributeValueId": "01914d0e-92a3-74b5-86c7-324354657689"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/disableproducts:read_writeDisable variant

Disables a variant, transitioning it to inactive status. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/listings/01914d0e-5e6f-7071-8283-9e0f10213245/variants/01914d0e-a3b4-75c6-97d8-43546576879a/disable
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-92a3-74b5-86c7-324354657689",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "optionValueId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12"
    }
  ],
  "options": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "attributeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "attributeValueId": "01914d0e-4d5e-7f60-b172-8d9e0f102134"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/archiveproducts:read_writeArchive variant

Archives a variant. If the variant is currently published, it will be automatically unpublished first. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/listings/01914d0e-b4c5-76d7-a8e9-546576879aab/variants/01914d0e-4d5e-7f60-b172-8d9e0f102134/archive
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-92a3-74b5-86c7-324354657689",
      "optionValueId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc"
    }
  ],
  "options": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-7081-7293-a4a5-102132435467",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "attributeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "attributeValueId": "01914d0e-a3b4-75c6-97d8-43546576879a"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/{variantId}/restoreproducts:read_writeRestore variant

Restores an archived variant to inactive status. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired
  • variantIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • isDefaultboolean
  • skustring
  • variantSignaturestring
  • statusstringOne of: draft · active · inactive · out_of_stock · archived
  • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
  • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
  • priceCurrencystring
  • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • promotionIdstring · uuid
    • namestring
    • salePriceinteger
    • frozenReferenceinteger
    • regularPriceinteger
    • discountVisibleboolean
    • statestringOne of: live · paused · not_live · no_discount_shown
    • saleEndsAtstring · date-time
  • barcodesarray<object>
    • idstring · uuid
    • barcodestring
    • typestringOne of: ean8 · ean13 · gtin12 · isbn13 · internal
  • mediaarray<object>
    • idstring · uuid
    • urlstringPublic URL resolved from the stored media path.
    • positioninteger
    • altTextstring
  • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionIdstring · uuid
    • optionValueIdstring · uuid
  • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>
  • attributeValuesarray<object>
    • idstring · uuid
    • attributeIdstring · uuid
    • attributeValueIdstring · uuid
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/listings/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/variants/01914d0e-c5d6-77e8-b9fa-6576879aabbc/restore
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "isDefault": false,
  "sku": "Sku",
  "variantSignature": "Variant signature",
  "status": "draft",
  "publicationStatus": "not_published",
  "priceAmount": 2999,
  "priceCurrency": "EUR",
  "activeSale": {
    "promotionId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "name": "Name",
    "salePrice": 129900,
    "frozenReference": 0,
    "regularPrice": 129900,
    "discountVisible": false,
    "state": "live",
    "saleEndsAt": "2026-09-10T09:24:11Z"
  },
  "barcodes": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "barcode": "Barcode",
      "type": "ean8"
    }
  ],
  "media": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "url": "https://storage.example.com/listing-photos/abc123.jpg",
      "position": 1,
      "altText": "Alt text"
    }
  ],
  "optionValues": [
    {
      "optionId": "01914d0e-92a3-74b5-86c7-324354657689",
      "optionValueId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc"
    }
  ],
  "options": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-7081-7293-a4a5-102132435467",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ],
  "attributeValues": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "attributeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "attributeValueId": "01914d0e-6f70-7182-9394-0f1021324356"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/listings/{listingId}/variants/bulkproducts:read_writeAdd variants in bulk

Adds a batch of variants to a listing atomically, minting any brand-new option values the combinations reference. Returns the created variant summaries and the listing's full refreshed option set. Requires the `products:read_write`…

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Request body · application/json

  • newOptionValuesobjectPer listing-option id, brand-new value labels to add to that option's set listing-wide. Keys are listing-option ids; values are lists of new value labels.
  • combinationsarray<object>requiredOne listing-option-id -> value-label map per new variant to create. Labels may be existing or declared in newOptionValues.

Response · 201

  • variantsarray<object>requiredThe newly created variants (draft, unpriced), in listing-detail variant shape.
    • idstring · uuid
    • isDefaultboolean
    • skustring
    • variantSignaturestring
    • statusstringOne of: draft · active · inactive · out_of_stock · archived
    • publicationStatusstringOne of: not_published · pending_review · in_review · published · hidden_by_admin · rejected · unpublished · merged
    • priceAmountintegerBase (regular) price in cents — the price-edit popover contract, never the sale price. The live sale is on `activeSale`.
    • priceCurrencystring
    • activeSaleobjectActive-sale framing for this variant, or null when no sale applies (M7). `priceAmount` stays the base price; this carries the live sale. No percentage.
    • barcodesarray<object>
    • mediaarray<object>
    • optionValuesarray<object>Defining option-value selections — the variant signature.
    • optionsarray<object>The parent listing's options and their values, mirroring listing detail. Used to resolve each option-value selection to its option name and value label.
    • attributeValuesarray<object>
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • optionsarray<object>requiredThe listing's full refreshed option set, so newly minted values resolve to labels.
    • idstring · uuid
    • namestring
    • positioninteger
    • valuesarray<object>

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/listings/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/variants/bulk
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "newOptionValues": {
    "01932a00-0000-7000-8000-000000000010": [
      "1024 GB"
    ]
  },
  "combinations": [
    {
      "01932a00-0000-7000-8000-000000000010": "1024 GB"
    }
  ]
}
jsonResponse · 201
{
  "variants": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "isDefault": false,
      "sku": "Sku",
      "variantSignature": "Variant signature",
      "status": "draft",
      "publicationStatus": "not_published",
      "priceAmount": 2999,
      "priceCurrency": "EUR",
      "activeSale": {
        "promotionId": "01914d0e-8192-73a4-b5b6-213243546578",
        "name": "Name",
        "salePrice": 129900,
        "frozenReference": 0,
        "regularPrice": 129900,
        "discountVisible": false,
        "state": "live",
        "saleEndsAt": "2026-09-10T09:24:11Z"
      },
      "barcodes": [
        {
          "id": "01914d0e-92a3-74b5-86c7-324354657689",
          "barcode": "Barcode",
          "type": "ean8"
        }
      ],
      "media": [
        {
          "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "url": "https://storage.example.com/listing-photos/abc123.jpg",
          "position": 1,
          "altText": "Alt text"
        }
      ],
      "optionValues": [
        {
          "optionId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
          "optionValueId": "01914d0e-7081-7293-a4a5-102132435467"
        }
      ],
      "options": [
        {
          "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "name": "Name",
          "position": 0,
          "values": [
            {}
          ]
        }
      ],
      "attributeValues": [
        {
          "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "attributeId": "01914d0e-6f70-7182-9394-0f1021324356",
          "attributeValueId": "01914d0e-92a3-74b5-86c7-324354657689"
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "options": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "name": "Name",
      "position": 0,
      "values": [
        {
          "id": "01914d0e-6f70-7182-9394-0f1021324356",
          "value": "Value",
          "priceDeltaAmount": 129900,
          "position": 0
        }
      ]
    }
  ]
}
write#

Public Carriers 1 operation

GET/rest/v1/showroom/carriers/{code}/terminalspublicList carrier terminals (public)

Lists an enabled carrier's active terminals in a country, grouped by city. Without a search term the full country list is returned; the optional search term filters by a case- and accent-insensitive name/address/city substring. No…

Requires

public

Path parameters

  • codestringrequired

Query parameters

  • countrystringrequiredISO 3166-1 alpha-2 destination country code
  • searchstringOptional case- and accent-insensitive substring filter over terminal name, address and city. Omit to receive the full active-terminal list; when provided, must be at least 2 characters.

Response · 200

  • itemsarray<object>required
    • citystringrequired
    • terminalsarray<object>required

Errors

400 · 404 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/carriers/Code/terminals?country=LT
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "city": "Vilnius",
      "terminals": [
        {
          "id": "Id",
          "externalId": "External id",
          "name": "Name",
          "address": "Address",
          "city": "City",
          "countryCode": "LT",
          "postalCode": "Postal code",
          "workingHours": "Working hours"
        }
      ]
    }
  ]
}
read#

Seller Imports 4 operations

POST/rest/v1/seller/stores/{storeId}/importsproducts:read_writeValidate CSV import

Uploads and validates a CSV import file. Returns validation summary with row counts. Answers 503 with `type` `/errors/file-storage-unavailable` when file storage cannot be reached; retry. Requires the `products:read_write` capability (the…

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • uploadIdstringrequiredSigned upload token from /rest/v1/uploads

Response · 201

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring · uuid
  • statusstringOne of: validated · processing · completed · failed
  • totalRowsinteger
  • validRowsinteger
  • errorRowsinteger
  • processedRowsinteger
  • succeededRowsinteger
  • failedRowsinteger
  • flowIdstring · uuid
  • uploadIdstring
  • originalFilenamestring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/imports
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "uploadId": "eyJrIjoi..."
}
jsonResponse · 201
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "storeId": "01914d0e-6f70-7182-9394-0f1021324356",
  "userId": "01914d0e-6f70-7182-9394-0f1021324356",
  "status": "validated",
  "totalRows": 120,
  "validRows": 118,
  "errorRows": 2,
  "processedRows": 118,
  "succeededRows": 116,
  "failedRows": 2,
  "flowId": "01914d0e-7081-7293-a4a5-102132435467",
  "uploadId": "Upload id",
  "originalFilename": "products.csv",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/stores/{storeId}/importsproducts:readList imports for a store

Returns a paginated list of the seller's imports for a store, newest first. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • afterstring · uuidCursor for forward pagination (UUID of last item on previous page)
  • beforestring · uuidCursor for backward pagination (UUID of first item on previous page)
  • limitintegerNumber of items per page
  • includeTotalCountbooleanInclude total count in response metadata

Response · 200

  • itemsarray<object>
    • idstring · uuid
    • storeIdstring · uuid
    • statusstringOne of: validated · processing · completed · failed
    • totalRowsinteger
    • validRowsinteger
    • errorRowsinteger
    • processedRowsinteger
    • succeededRowsinteger
    • failedRowsinteger
    • flowIdstring · uuid
    • originalFilenamestring
    • failureReasonstringCode of why the import failed; the client shows its own translated text for it. Null unless the import could not be started.One of: import_not_started
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/imports
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "storeId": "01914d0e-8192-73a4-b5b6-213243546578",
      "status": "validated",
      "totalRows": 120,
      "validRows": 118,
      "errorRows": 2,
      "processedRows": 118,
      "succeededRows": 116,
      "failedRows": 2,
      "flowId": "01914d0e-92a3-74b5-86c7-324354657689",
      "originalFilename": "products.csv",
      "failureReason": "import_not_started",
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "prevCursor": "01914d0e-b4c5-76d7-a8e9-546576879aab",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/seller/stores/{storeId}/imports/{importId}products:readGet import

Retrieves the import status and all row results. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequired
  • importIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring · uuid
  • statusstringOne of: validated · processing · completed · failed
  • totalRowsinteger
  • validRowsinteger
  • errorRowsinteger
  • processedRowsinteger
  • succeededRowsinteger
  • failedRowsinteger
  • flowIdstring · uuid
  • uploadIdstring
  • originalFilenamestring
  • failureReasonstringCode of why the import failed; the client shows its own translated text for it. Null unless the import could not be started.One of: import_not_started
  • createdAtstring · date-time
  • updatedAtstring · date-time
  • rowsarray<object>
    • idstring · uuid
    • rowNumberinteger1-based row number in the file as a spreadsheet shows it: the header row is 1, blank rows keep their number, and a quoted cell spanning several lines stays one row.
    • handlestring
    • outcomestringOne of: pending · success · failed · skipped
    • warningsarray<string>Human-readable validation messages for a failed row; null for rows that passed validation.
    • listingIdstring · uuid
    • createdAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/imports/01914d0e-92a3-74b5-86c7-324354657689
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "storeId": "01914d0e-92a3-74b5-86c7-324354657689",
  "userId": "01914d0e-7081-7293-a4a5-102132435467",
  "status": "validated",
  "totalRows": 120,
  "validRows": 118,
  "errorRows": 2,
  "processedRows": 118,
  "succeededRows": 116,
  "failedRows": 2,
  "flowId": "01914d0e-6f70-7182-9394-0f1021324356",
  "uploadId": "Upload id",
  "originalFilename": "products.csv",
  "failureReason": "import_not_started",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "rows": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "rowNumber": 2,
      "handle": "Handle",
      "outcome": "pending",
      "warnings": [
        "Warnings"
      ],
      "listingId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "createdAt": "2026-09-10T09:24:11Z"
    }
  ]
}
read#
POST/rest/v1/seller/stores/{storeId}/imports/{importId}/confirmproducts:read_writeConfirm import

Confirms a validated import to start processing. Creates a Flow saga and kicks off the Temporal workflow. Answers 503 with `type` `/errors/file-storage-unavailable` when file storage cannot be reached; the import stays `validated` and the…

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequired
  • importIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • userIdstring · uuid
  • statusstringOne of: validated · processing · completed · failed
  • totalRowsinteger
  • validRowsinteger
  • errorRowsinteger
  • processedRowsinteger
  • succeededRowsinteger
  • failedRowsinteger
  • flowIdstring · uuid
  • uploadIdstring
  • originalFilenamestring
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/imports/01914d0e-6f70-7182-9394-0f1021324356/confirm
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "storeId": "01914d0e-8192-73a4-b5b6-213243546578",
  "userId": "01914d0e-8192-73a4-b5b6-213243546578",
  "status": "validated",
  "totalRows": 120,
  "validRows": 118,
  "errorRows": 2,
  "processedRows": 118,
  "succeededRows": 116,
  "failedRows": 2,
  "flowId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "uploadId": "Upload id",
  "originalFilename": "products.csv",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#

Public Stores 4 operations

GET/rest/v1/showroom/stores/{storeId}/shipping-optionspublicGet store shipping options (public)

Returns available shipping methods for the given store and destination country. No authentication required. Used for PDP "Delivery from" preview. Returns an empty list when no methods cover the destination country.

Requires

public

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • countryCodestringrequiredISO 3166-1 alpha-2 destination country code

Response · 200

  • itemsarray<object>Available shipping options for the given destination
    • methodIdstring · uuid
    • methodNamestring
    • rateobject
    • estimateobject
    • freeThresholdobjectFree delivery threshold (null when not enabled)

Errors

400 · 404 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/stores/01914d0e-8192-73a4-b5b6-213243546578/shipping-options?countryCode=LT
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "methodId": "01914d0e-8192-73a4-b5b6-213243546578",
      "methodName": "Standard Delivery",
      "rate": {
        "amount": 499,
        "currency": "EUR"
      },
      "estimate": {
        "minDays": 2,
        "maxDays": 5
      },
      "freeThreshold": {
        "amount": 5000,
        "currency": "EUR"
      }
    }
  ]
}
read#
GET/rest/v1/showroom/stores/{storeId}/pickup-locationspublicGet store pickup locations (public)

Returns active pickup locations for a store with address, pickup windows, customer notes, and optional map pin coordinates. No authentication required. Used to display pickup points in the checkout flow.

Requires

public

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • itemsarray<object>Active pickup locations for the store
    • idstring · uuid
    • namestring
    • addressobject
    • pickupWindowsarray<object>
    • customerNotesstringPickup instructions for the customer
    • mapPinLatnumber · floatMap pin latitude (-90 to 90)
    • mapPinLngnumber · floatMap pin longitude (-180 to 180)

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/showroom/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/pickup-locations
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "ebb017c7-e2fe-7700-add8-d429a3b9ea12",
      "name": "TechVault — Vilnius",
      "address": {
        "street": "Konstitucijos pr. 7",
        "city": "Vilnius",
        "postalCode": "09308",
        "countryCode": "LT"
      },
      "pickupWindows": [
        {
          "dayOfWeek": 1,
          "open": "09:00",
          "close": "18:00"
        }
      ],
      "customerNotes": "Ring the bell at the side entrance.",
      "mapPinLat": 54.694893,
      "mapPinLng": 25.273058
    }
  ]
}
read#
GET/rest/v1/showroom/stores/{storeId}publicGet store detail (public)

Returns store details for a given active store. No authentication required. Returns 404 for inactive or nonexistent stores.

Requires

public

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • idstring · uuidrequiredStore unique identifier
  • namestringrequired
  • descriptionstringrequired
  • statusstringrequiredOne of: active
  • logoUrlstring · uriFull URL to store logo
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)

Errors

404 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/stores/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "name": "My Electronics Store",
  "description": "Selling quality electronics",
  "status": "active",
  "logoUrl": "https://api.example.com",
  "createdAt": "2026-09-10T09:24:11Z"
}
read#
GET/rest/v1/showroom/stores/{storeId}/locker-optionspublicGet store locker options (public)

Returns available parcel-locker methods for the given store and destination country. No authentication required. Returns an empty list when no active method covers the destination country.

Requires

public

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • countryCodestringrequiredISO 3166-1 alpha-2 destination country code

Response · 200

  • itemsarray<object>requiredAvailable locker options for the given destination
    • methodIdstring · uuid
    • carrierNetworkCodestring
    • carrierNetworkNamestring
    • priceAmountintegerFlat buyer price in cents
    • priceCurrencystring
    • freeThresholdEnabledboolean
    • freeThresholdAmountintegerFree-delivery threshold amount in cents
    • freeThresholdCurrencystring
    • estimateMinDaysinteger
    • estimateMaxDaysinteger

Errors

400 · 404 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/stores/01914d0e-6f70-7182-9394-0f1021324356/locker-options?countryCode=LT
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "methodId": "01914d0e-6f70-7182-9394-0f1021324356",
      "carrierNetworkCode": "omniva",
      "carrierNetworkName": "Omniva",
      "priceAmount": 299,
      "priceCurrency": "EUR",
      "freeThresholdEnabled": false,
      "freeThresholdAmount": 5000,
      "freeThresholdCurrency": "EUR",
      "estimateMinDays": 1,
      "estimateMaxDays": 2
    }
  ]
}
read#

Store Feedback 7 operations

GET/rest/v1/showroom/stores/{storeId}/feedbackpublicList store feedback (public overlay)

Public overlay list of a store's published feedback with a store-wide rating aggregate head. Optionally filtered to a single rating band and sorted by recency, highest, or lowest rating. No authentication required.

Requires

public

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • ratinginteger
  • sortstringOne of: recent · highest · lowest
  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountboolean

Response · 200

  • aggregateobject
    • averageRatingnumber · float
    • publishedCountinteger
    • starCountsarray<integer>
  • itemsarray<object>
    • idstring · uuid
    • ratinginteger
    • bodystring
    • photosarray<object>
    • buyerDisplayNamestring
    • purchaseMonthstring
    • feedbackAtstring · date-time
    • sellerResponseobject
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

400 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/stores/01914d0e-a3b4-75c6-97d8-43546576879a/feedback
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "aggregate": {
    "averageRating": 4.6,
    "publishedCount": 128,
    "starCounts": [
      96,
      20,
      8,
      2,
      2
    ]
  },
  "items": [
    {
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "rating": 0,
      "body": "Body",
      "photos": [
        {
          "url": "https://api.example.com"
        }
      ],
      "buyerDisplayName": "Marija K.",
      "purchaseMonth": "2026-06",
      "feedbackAt": "2026-09-10T09:24:11Z",
      "sellerResponse": {
        "body": "Body",
        "photos": [
          {
            "url": "https://api.example.com"
          }
        ],
        "respondedAt": "2026-09-10T09:24:11Z"
      }
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-7081-7293-a4a5-102132435467",
    "prevCursor": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "totalCount": 129900
  }
}
read#
POST/rest/v1/showroom/stores/{storeId}/feedbackauthenticatedSubmit store feedback

Submit the authenticated buyer's feedback for a store. Re-checks the proof-of-purchase gate: an unqualified buyer is rejected (422), a duplicate submission conflicts (409), and an unreachable qualification service returns 502. Publishes…

Requires

authenticated

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • ratingintegerrequired
  • bodystring
  • photoUploadIdsarray<string>

Response · 201

  • feedbackIdstring · uuid

Errors

400 · 401 · 403 · 409 · 422 · 500 · 502 · 503 — See the error reference

httpRequest
POST /rest/v1/showroom/stores/01914d0e-a3b4-75c6-97d8-43546576879a/feedback
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "rating": 5,
  "body": "Body",
  "photoUploadIds": [
    "Photo upload ids"
  ]
}
jsonResponse · 201
{
  "feedbackId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12"
}
write#
GET/rest/v1/showroom/stores/{storeId}/feedback/mineauthenticatedGet my store feedback

The authenticated buyer's feedback for a store. When none exists, includes whether the buyer currently qualifies to leave feedback (degrades to false on an upstream outage).

Requires

authenticated

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • qualifiedboolean
  • feedbackobject
    • idstring · uuid
    • storeIdstring · uuid
    • ratinginteger
    • bodystring
    • photosarray<object>
    • purchaseMonthstring
    • submittedAtstring · date-time
    • lastEditedAtstring · date-time
    • statestringOne of: published · pending_review · removed

Errors

401 · 403 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/stores/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/feedback/mine
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "qualified": false,
  "feedback": {
    "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
    "storeId": "01914d0e-7081-7293-a4a5-102132435467",
    "rating": 0,
    "body": "Body",
    "photos": [
      {
        "url": "https://api.example.com"
      }
    ],
    "purchaseMonth": "2026-06",
    "submittedAt": "2026-09-10T09:24:11Z",
    "lastEditedAt": "2026-09-10T09:24:11Z",
    "state": "published"
  }
}
read#
DELETE/rest/v1/showroom/stores/{storeId}/feedback/mineauthenticatedWithdraw store feedback

Withdraw the authenticated buyer's feedback for a store — a hard delete of the aggregate (seller response and flags cascade) plus removal of published public photo copies. Reopens the one-per-(store, customer) slot.

Requires

authenticated

Path parameters

  • storeIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 — See the error reference

httpRequest
DELETE /rest/v1/showroom/stores/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/feedback/mine
Authorization: Bearer $TOKEN
write#
POST/rest/v1/showroom/stores/{storeId}/feedback/reviseauthenticatedRevise store feedback

Edit the authenticated buyer's existing feedback in place. Carries the full desired photo set as fresh upload tokens (previous photos are replaced). The first-publish instant is preserved and the content version bumps. Missing feedback…

Requires

authenticated

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • ratingintegerrequired
  • bodystring
  • photoUploadIdsarray<string>

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • ratinginteger
  • bodystring
  • photosarray<object>
    • urlstring · uri
  • purchaseMonthstring
  • submittedAtstring · date-time
  • lastEditedAtstring · date-time
  • statestringOne of: published · pending_review · removed

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/showroom/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/feedback/revise
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "rating": 5,
  "body": "Body",
  "photoUploadIds": [
    "Photo upload ids"
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "storeId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "rating": 0,
  "body": "Body",
  "photos": [
    {
      "url": "https://api.example.com"
    }
  ],
  "purchaseMonth": "2026-06",
  "submittedAt": "2026-09-10T09:24:11Z",
  "lastEditedAt": "2026-09-10T09:24:11Z",
  "state": "published"
}
write#
GET/rest/v1/showroom/my/store-feedbackauthenticatedList my store feedback (all stores)

Cursor-paginated list of the authenticated buyer's feedback across every store.

Requires

authenticated

Query parameters

  • afterstring · uuid
  • beforestring · uuid
  • limitinteger

Response · 200

  • itemsarray<object>
    • idstring · uuid
    • storeIdstring · uuid
    • ratinginteger
    • bodystring
    • photosarray<object>
    • purchaseMonthstring
    • submittedAtstring · date-time
    • lastEditedAtstring · date-time
    • statestringOne of: published · pending_review · removed
    • storeNamestring
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

400 · 401 · 403 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/my/store-feedback
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "storeId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "rating": 0,
      "body": "Body",
      "photos": [
        {
          "url": "https://api.example.com"
        }
      ],
      "purchaseMonth": "2026-06",
      "submittedAt": "2026-09-10T09:24:11Z",
      "lastEditedAt": "2026-09-10T09:24:11Z",
      "state": "published",
      "storeName": "Vilnius Electronics"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-a3b4-75c6-97d8-43546576879a",
    "prevCursor": "01914d0e-6f70-7182-9394-0f1021324356",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/showroom/stores/ratingspublicBatch store ratings

Public batch rating probe for store list cards: one rating figure per requested store (max 50). A store with no published feedback yields a null average and a zero count. No authentication required.

Requires

public

Query parameters

  • storeIdsstringrequiredComma-separated store ids (max 50)

Response · 200

  • itemsarray<object>
    • storeIdstring · uuid
    • averageRatingnumber · float
    • publishedCountinteger

Errors

400 · 500 — See the error reference

httpRequest
GET /rest/v1/showroom/stores/ratings?storeIds=01914d0e-8192-73a4-b5b6-213243546578%2C01914d0e-6f70-7182-9394-0f1021324356
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "storeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "averageRating": 0,
      "publishedCount": 0
    }
  ]
}
read#

Seller Store Feedback 11 operations

GET/rest/v1/seller/stores/{storeId}/feedbackorders:readList store feedback (seller hub)

The seller feedback hub for an owned store: filtered, sorted, cursor-paginated feedback with a per-row unread flag. A foreign/unknown store returns 404. Requires the `orders:read` capability (the Orders area at read level).

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • qstring
  • ratingarray<integer>
  • responsestringOne of: responded · none
  • statestringOne of: published · pending_review · removed
  • flaggedstringOne of: by_me · not_flagged
  • sortstringOne of: createdAt · rating
  • dirstringOne of: asc · desc
  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountboolean

Response · 200

  • itemsarray<object>
    • idstring · uuid
    • buyerNamestring
    • ratinginteger
    • bodystring
    • photoCountinteger
    • orderRefstring
    • feedbackAtstring · date-time
    • statestringOne of: published · pending_review · removed
    • responseStatusstringOne of: responded · none
    • flagobject
    • unreadboolean
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/feedback
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "buyerName": "Marija Kovaite",
      "rating": 0,
      "body": "Body",
      "photoCount": 2,
      "orderRef": "MKT-2026-000002",
      "feedbackAt": "2026-09-10T09:24:11Z",
      "state": "published",
      "responseStatus": "responded",
      "flag": {
        "status": "open"
      },
      "unread": false
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
    "prevCursor": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/seller/stores/{storeId}/feedback/aggregateorders:readStore feedback aggregate

The seller-hub rating rollup — published-only mean, published count, always-zero pending-review count, and the per-star breakdown 5-star to 1-star. Requires the `orders:read` capability (the Orders area at read level).

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • averageRatingnumber · float
  • publishedCountinteger
  • pendingReviewCountinteger
  • starCountsarray<integer>

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/feedback/aggregate
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "averageRating": 4.6,
  "publishedCount": 128,
  "pendingReviewCount": 0,
  "starCounts": [
    96,
    20,
    8,
    2,
    2
  ]
}
read#
GET/rest/v1/seller/stores/{storeId}/feedback/unread-countorders:readStore feedback unread count

The seller's unread published-feedback count for a store — drives the sidebar unread badge. Requires the `orders:read` capability (the Orders area at read level).

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • countinteger

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/feedback/unread-count
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "count": 3
}
read#
GET/rest/v1/seller/stores/{storeId}/feedback/trendorders:readStore feedback rating trend

Lifetime running-average rating trend, returning the points whose first-publish instant falls inside the requested window. Requires the `orders:read` capability (the Orders area at read level).

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • fromstring · date-timerequired
  • tostring · date-timerequired

Response · 200

  • lifetimeAveragenumber · float
  • lifetimeCountinteger
  • trendobject
    • inflowCountintegerFeedback published inside the window
    • runningAveragearray<number>Running average after each in-window publication, rounded to two decimals.
    • deltaPointsnumber · floatMovement of the running average across the window, in rating points.

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/feedback/trend?from=2026-09-10T09%3A24%3A11Z&to=2026-09-10T09%3A24%3A11Z
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "lifetimeAverage": 4.6,
  "lifetimeCount": 128,
  "trend": {
    "inflowCount": 12,
    "runningAverage": [
      4.5,
      4.55,
      4.6
    ],
    "deltaPoints": 0.1
  }
}
read#
POST/rest/v1/seller/stores/{storeId}/feedback/hub-vieworders:readRecord hub view

Re-baseline the store's unread count to the previous hub-view session. Answers 204. Requires the `orders:read` capability (the Orders area at read level).

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/feedback/hub-view
Authorization: Bearer $TOKEN
read#
GET/rest/v1/seller/stores/{storeId}/feedback/{feedbackId}orders:readGet store feedback detail

Full seller-side detail for one feedback — buyer identity, frozen qualifying-order snapshot, seller response, active flag, and the canRespond/canFlag/isUnread action gates. Requires the `orders:read` capability (the Orders area at read…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired
  • feedbackIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • buyerNamestring
  • buyerInitialsstring
  • ratinginteger
  • bodystring
  • photosarray<object>
    • urlstring · uri
  • purchaseMonthstring
  • feedbackAtstring · date-time
  • lastEditedAtstring · date-time
  • statestringOne of: published · pending_review · removed
  • orderobject
    • idstring · uuid
    • refstring
    • itemsSummarystring
    • deliveredAtstring · date-time
    • totalCentsinteger
    • currencystring
  • responseobject
    • bodystring
    • photosarray<object>
    • respondedAtstring · date-time
    • lastEditedAtstring · date-time
  • flagobject
    • statusstringOne of: open · resolved_kept · resolved_removed
    • reasonstring
    • flaggedAtstring · date-time
    • resolvedAtstring · date-time
  • canRespondboolean
  • canFlagboolean
  • isUnreadboolean

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/feedback/01914d0e-4d5e-7f60-b172-8d9e0f102134
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "buyerName": "Buyer name",
  "buyerInitials": "Buyer initials",
  "rating": 0,
  "body": "Body",
  "photos": [
    {
      "url": "https://api.example.com"
    }
  ],
  "purchaseMonth": "2026-06",
  "feedbackAt": "2026-09-10T09:24:11Z",
  "lastEditedAt": "2026-09-10T09:24:11Z",
  "state": "published",
  "order": {
    "id": "01914d0e-7081-7293-a4a5-102132435467",
    "ref": "MKT-2026-000002",
    "itemsSummary": "1 item",
    "deliveredAt": "2026-09-10T09:24:11Z",
    "totalCents": 129900,
    "currency": "EUR"
  },
  "response": {
    "body": "Body",
    "photos": [
      {
        "url": "https://api.example.com"
      }
    ],
    "respondedAt": "2026-09-10T09:24:11Z",
    "lastEditedAt": "2026-09-10T09:24:11Z"
  },
  "flag": {
    "status": "open",
    "reason": "Reason",
    "flaggedAt": "2026-09-10T09:24:11Z",
    "resolvedAt": "2026-09-10T09:24:11Z"
  },
  "canRespond": false,
  "canFlag": false,
  "isUnread": false
}
read#
POST/rest/v1/seller/stores/{storeId}/feedback/{feedbackId}/readorders:readMark store feedback read

Stamp the seller-read instant on one feedback (idempotent), clearing it from the unread badge. Answers 204. Requires the `orders:read` capability (the Orders area at read level).

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired
  • feedbackIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/feedback/01914d0e-7081-7293-a4a5-102132435467/read
Authorization: Bearer $TOKEN
read#
POST/rest/v1/seller/stores/{storeId}/feedback/{feedbackId}/responseorders:read_writeRespond to store feedback

Attach the seller's first response. Allowed only while the feedback is published (else 422) and has no existing response (else 409). Returns the refreshed detail. Answers 503 with `type` `/errors/file-storage-unavailable` when file storage…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequired
  • feedbackIdstring · uuidrequired

Request body · application/json

  • bodystringrequired
  • photoUploadIdsarray<string>

Response · 200

  • idstring · uuid
  • buyerNamestring
  • buyerInitialsstring
  • ratinginteger
  • bodystring
  • photosarray<object>
    • urlstring · uri
  • purchaseMonthstring
  • feedbackAtstring · date-time
  • lastEditedAtstring · date-time
  • statestringOne of: published · pending_review · removed
  • orderobject
    • idstring · uuid
    • refstring
    • itemsSummarystring
    • deliveredAtstring · date-time
    • totalCentsinteger
    • currencystring
  • responseobject
    • bodystring
    • photosarray<object>
    • respondedAtstring · date-time
    • lastEditedAtstring · date-time
  • flagobject
    • statusstringOne of: open · resolved_kept · resolved_removed
    • reasonstring
    • flaggedAtstring · date-time
    • resolvedAtstring · date-time
  • canRespondboolean
  • canFlagboolean
  • isUnreadboolean

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/feedback/01914d0e-4d5e-7f60-b172-8d9e0f102134/response
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "body": "Body",
  "photoUploadIds": [
    "Photo upload ids"
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "buyerName": "Buyer name",
  "buyerInitials": "Buyer initials",
  "rating": 0,
  "body": "Body",
  "photos": [
    {
      "url": "https://api.example.com"
    }
  ],
  "purchaseMonth": "2026-06",
  "feedbackAt": "2026-09-10T09:24:11Z",
  "lastEditedAt": "2026-09-10T09:24:11Z",
  "state": "published",
  "order": {
    "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "ref": "MKT-2026-000002",
    "itemsSummary": "1 item",
    "deliveredAt": "2026-09-10T09:24:11Z",
    "totalCents": 129900,
    "currency": "EUR"
  },
  "response": {
    "body": "Body",
    "photos": [
      {
        "url": "https://api.example.com"
      }
    ],
    "respondedAt": "2026-09-10T09:24:11Z",
    "lastEditedAt": "2026-09-10T09:24:11Z"
  },
  "flag": {
    "status": "open",
    "reason": "Reason",
    "flaggedAt": "2026-09-10T09:24:11Z",
    "resolvedAt": "2026-09-10T09:24:11Z"
  },
  "canRespond": false,
  "canFlag": false,
  "isUnread": false
}
write#
POST/rest/v1/seller/stores/{storeId}/feedback/{feedbackId}/response/reviseorders:read_writeRevise store feedback response

Edit the seller's existing response in place. Returns the refreshed detail. Answers 503 with `type` `/errors/file-storage-unavailable` when file storage cannot be reached; retry. Requires the `orders:read_write` capability (the Orders area…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequired
  • feedbackIdstring · uuidrequired

Request body · application/json

  • bodystringrequired
  • photoUploadIdsarray<string>

Response · 200

  • idstring · uuid
  • buyerNamestring
  • buyerInitialsstring
  • ratinginteger
  • bodystring
  • photosarray<object>
    • urlstring · uri
  • purchaseMonthstring
  • feedbackAtstring · date-time
  • lastEditedAtstring · date-time
  • statestringOne of: published · pending_review · removed
  • orderobject
    • idstring · uuid
    • refstring
    • itemsSummarystring
    • deliveredAtstring · date-time
    • totalCentsinteger
    • currencystring
  • responseobject
    • bodystring
    • photosarray<object>
    • respondedAtstring · date-time
    • lastEditedAtstring · date-time
  • flagobject
    • statusstringOne of: open · resolved_kept · resolved_removed
    • reasonstring
    • flaggedAtstring · date-time
    • resolvedAtstring · date-time
  • canRespondboolean
  • canFlagboolean
  • isUnreadboolean

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/feedback/01914d0e-7081-7293-a4a5-102132435467/response/revise
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "body": "Body",
  "photoUploadIds": [
    "Photo upload ids"
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "buyerName": "Buyer name",
  "buyerInitials": "Buyer initials",
  "rating": 0,
  "body": "Body",
  "photos": [
    {
      "url": "https://api.example.com"
    }
  ],
  "purchaseMonth": "2026-06",
  "feedbackAt": "2026-09-10T09:24:11Z",
  "lastEditedAt": "2026-09-10T09:24:11Z",
  "state": "published",
  "order": {
    "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
    "ref": "MKT-2026-000002",
    "itemsSummary": "1 item",
    "deliveredAt": "2026-09-10T09:24:11Z",
    "totalCents": 129900,
    "currency": "EUR"
  },
  "response": {
    "body": "Body",
    "photos": [
      {
        "url": "https://api.example.com"
      }
    ],
    "respondedAt": "2026-09-10T09:24:11Z",
    "lastEditedAt": "2026-09-10T09:24:11Z"
  },
  "flag": {
    "status": "open",
    "reason": "Reason",
    "flaggedAt": "2026-09-10T09:24:11Z",
    "resolvedAt": "2026-09-10T09:24:11Z"
  },
  "canRespond": false,
  "canFlag": false,
  "isUnread": false
}
write#
POST/rest/v1/seller/stores/{storeId}/feedback/{feedbackId}/flagorders:read_writeFlag store feedback

Raise a moderation flag against a feedback. Rejected while an open flag exists or the feedback is not published (422). Re-flagging is allowed only after the buyer revises the content. Returns the refreshed detail. Requires the…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequired
  • feedbackIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 200

  • idstring · uuid
  • buyerNamestring
  • buyerInitialsstring
  • ratinginteger
  • bodystring
  • photosarray<object>
    • urlstring · uri
  • purchaseMonthstring
  • feedbackAtstring · date-time
  • lastEditedAtstring · date-time
  • statestringOne of: published · pending_review · removed
  • orderobject
    • idstring · uuid
    • refstring
    • itemsSummarystring
    • deliveredAtstring · date-time
    • totalCentsinteger
    • currencystring
  • responseobject
    • bodystring
    • photosarray<object>
    • respondedAtstring · date-time
    • lastEditedAtstring · date-time
  • flagobject
    • statusstringOne of: open · resolved_kept · resolved_removed
    • reasonstring
    • flaggedAtstring · date-time
    • resolvedAtstring · date-time
  • canRespondboolean
  • canFlagboolean
  • isUnreadboolean

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/feedback/01914d0e-5e6f-7071-8283-9e0f10213245/flag
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": "Reason"
}
jsonResponse · 200
{
  "id": "01914d0e-6f70-7182-9394-0f1021324356",
  "buyerName": "Buyer name",
  "buyerInitials": "Buyer initials",
  "rating": 0,
  "body": "Body",
  "photos": [
    {
      "url": "https://api.example.com"
    }
  ],
  "purchaseMonth": "2026-06",
  "feedbackAt": "2026-09-10T09:24:11Z",
  "lastEditedAt": "2026-09-10T09:24:11Z",
  "state": "published",
  "order": {
    "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "ref": "MKT-2026-000002",
    "itemsSummary": "1 item",
    "deliveredAt": "2026-09-10T09:24:11Z",
    "totalCents": 129900,
    "currency": "EUR"
  },
  "response": {
    "body": "Body",
    "photos": [
      {
        "url": "https://api.example.com"
      }
    ],
    "respondedAt": "2026-09-10T09:24:11Z",
    "lastEditedAt": "2026-09-10T09:24:11Z"
  },
  "flag": {
    "status": "open",
    "reason": "Reason",
    "flaggedAt": "2026-09-10T09:24:11Z",
    "resolvedAt": "2026-09-10T09:24:11Z"
  },
  "canRespond": false,
  "canFlag": false,
  "isUnread": false
}
write#
GET/rest/v1/seller/stores/{storeId}/customers/{customerId}/feedbackorders:readGet a customer's store feedback (CRM embed)

The seller's view of a single customer's feedback for the store — the embed used on the customer CRM detail page. Returns null feedback when the customer has left none. Requires the `orders:read` capability (the Orders area at read level).

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequired
  • customerIdstring · uuidrequired

Response · 200

  • feedbackobject
    • idstring · uuid
    • buyerNamestring
    • buyerInitialsstring
    • ratinginteger
    • bodystring
    • photosarray<object>
    • purchaseMonthstring
    • feedbackAtstring · date-time
    • lastEditedAtstring · date-time
    • statestringOne of: published · pending_review · removed
    • orderobject
    • responseobject
    • flagobject
    • canRespondboolean
    • canFlagboolean
    • isUnreadboolean

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/customers/01914d0e-a3b4-75c6-97d8-43546576879a/feedback
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "feedback": {
    "id": "01914d0e-92a3-74b5-86c7-324354657689",
    "buyerName": "Buyer name",
    "buyerInitials": "Buyer initials",
    "rating": 0,
    "body": "Body",
    "photos": [
      {
        "url": "https://api.example.com"
      }
    ],
    "purchaseMonth": "2026-06",
    "feedbackAt": "2026-09-10T09:24:11Z",
    "lastEditedAt": "2026-09-10T09:24:11Z",
    "state": "published",
    "order": {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "ref": "MKT-2026-000002",
      "itemsSummary": "1 item",
      "deliveredAt": "2026-09-10T09:24:11Z",
      "totalCents": 129900,
      "currency": "EUR"
    },
    "response": {
      "body": "Body",
      "photos": [
        {
          "url": "https://api.example.com"
        }
      ],
      "respondedAt": "2026-09-10T09:24:11Z",
      "lastEditedAt": "2026-09-10T09:24:11Z"
    },
    "flag": {
      "status": "open",
      "reason": "Reason",
      "flaggedAt": "2026-09-10T09:24:11Z",
      "resolvedAt": "2026-09-10T09:24:11Z"
    },
    "canRespond": false,
    "canFlag": false,
    "isUnread": false
  }
}
read#

Seller Promotions 6 operations

GET/rest/v1/seller/stores/{storeId}/promotionspromotions:readList the store's promotions (sales + coupons)

Returns the Promotions Hub — a mixed, cursor-paginated feed of the store's sales and coupons, sorted by start-date descending. Filter by `type` (sale/coupon), lifecycle `status`, or a case-insensitive `search` on sale internal name /…

Requires

promotions:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountboolean
  • typestringOne of: sale · coupon
  • statusstringOne of: draft · scheduled · active · ended · cancelled · expired · deactivated
  • searchstringCase-insensitive search on sale name or coupon code

Response · 200

  • itemsarray<object>
    • kindstringOne of: sale · coupon
    • idstring · uuid
    • namestringSale internal name (coupons use the code)
    • statusstringUnion lifecycle status across sales and coupons
    • startAtstring · date-time
    • endAtstring · date-time
    • createdAtstring · date-time
    • saleobjectPresent only when `kind` is `sale`.
    • couponobjectPresent only when `kind` is `coupon`.
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-a3b4-75c6-97d8-43546576879a/promotions
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "kind": "sale",
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "name": "Name",
      "status": "Status",
      "startAt": "2026-09-10T09:24:11Z",
      "endAt": "2026-09-10T09:24:11Z",
      "createdAt": "2026-09-10T09:24:11Z",
      "sale": {
        "variantCount": 0,
        "listingCount": 0,
        "depthMinPercent": 0,
        "depthMaxPercent": 0
      },
      "coupon": {
        "code": "Code",
        "description": "Description",
        "target": "items",
        "timesUsed": 0,
        "totalUses": 129900,
        "eligibleVariantCount": 0,
        "eligibleListingCount": 0,
        "discount": {
          "kind": "percent",
          "percent": 0,
          "capAmount": 129900,
          "fixedAmount": 129900,
          "currency": "EUR"
        }
      }
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "prevCursor": "01914d0e-7081-7293-a4a5-102132435467",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/seller/stores/{storeId}/promotions/statspromotions:readPromotions Hub segment counts

Returns the Promotions Hub segment counts: `all`, `active`, `scheduled`, `drafts`, and `finished` (terminal sales + coupons) — the filter-chip tallies.

Requires

promotions:read

Path parameters

  • storeIdstring · uuidrequired

Response · 200

  • allinteger
  • activeinteger
  • scheduledinteger
  • draftsinteger
  • finishedintegerTerminal sales + coupons

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/promotions/stats
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "all": 0,
  "active": 0,
  "scheduled": 0,
  "drafts": 0,
  "finished": 0
}
read#
GET/rest/v1/seller/stores/{storeId}/promotions/variant-pickerpromotions:readSale-authoring variant picker

Returns the store's listing/variant tree for the sale wizard, paged per listing: each variant's current base price, a live 30-day reference preview, and — when a target window (`windowStartsAt`/`windowEndsAt`, both-or-neither) is supplied…

Requires

promotions:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • searchstringCase-insensitive search on title, variant SKU, or variant barcode
  • windowStartsAtstring · date-timeStart of the sale window being authored. A date (YYYY-MM-DD) means midnight at the start of that day in the platform time zone (Europe/Vilnius); a date-time without an offset is read in the same zone. Supplied together with windowEndsAt or…
  • windowEndsAtstring · date-timeEnd of the sale window being authored, later than windowStartsAt. A date (YYYY-MM-DD) means midnight at the start of that day in the platform time zone (Europe/Vilnius); a date-time without an offset is read in the same zone. Supplied…
  • excludeSaleIdstring · uuidThe sale being edited; its own variants are left out of the conflict check. Omit it for a new sale; an empty value counts as not supplied.

Response · 200

  • itemsarray<object>
    • listingIdstring · uuid
    • titlestring
    • thumbnailUrlstringListing primary photo path (null when the listing has no media)
    • variantsarray<object>
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/promotions/variant-picker
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "listingId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "title": "Title",
      "thumbnailUrl": "Thumbnail url",
      "variants": [
        {
          "listingVariantId": "01914d0e-92a3-74b5-86c7-324354657689",
          "label": "Label",
          "isDefault": false,
          "basePriceAmount": 129900,
          "basePriceCurrency": "EUR",
          "liveToBuyers": false,
          "referencePreviewAmount": 129900,
          "conflict": {
            "saleId": "01914d0e-7081-7293-a4a5-102132435467",
            "saleName": "Sale name",
            "startsAt": "2026-09-10T09:24:11Z",
            "endsAt": "2026-09-10T09:24:11Z"
          }
        }
      ]
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-8192-73a4-b5b6-213243546578",
    "prevCursor": "01914d0e-8192-73a4-b5b6-213243546578",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}promotions:readSale detail

Returns a sale's configuration, its variants table (base price, 30-day reference — frozen or a live preview — sale price, what the buyer currently sees, and the per-line status pill with auto-pause context), and one embedded keyset page of…

Requires

promotions:read

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequiredSale identifier

Query parameters

  • activityAfterstring · uuid
  • activityBeforestring · uuid
  • activityLimitinteger

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • issuerstringOne of: store · platform
  • internalNamestring
  • statusstringOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-time
  • endsAtstring · date-time
  • activatedAtstring · date-time
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time
  • variantsarray<object>
    • promotionVariantIdstring · uuid
    • listingVariantIdstring · uuid
    • listingIdstring · uuid
    • saleAmountintegerConfigured sale price in cents. Null while an unpriced Draft line; `buyerSeesAmount` and `activeSale` are then null too (there is no price to overlay).
    • currencystring
    • baseAmountintegerBase (regular) price in cents
    • referenceobject
    • buyerSeesAmountintegerEffective price the buyer currently sees, in cents
    • discountVisibleboolean
    • activeSaleobjectBuyer framing (struck pair only, never a percentage)
    • pillstringPer-line status pill
    • pauseobject
  • activityTrailobject
    • itemsarray<object>
    • _metadataobject

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/promotions/sales/01914d0e-4d5e-7f60-b172-8d9e0f102134
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-7081-7293-a4a5-102132435467",
  "storeId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "issuer": "store",
  "internalName": "Internal name",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "promotionVariantId": "01914d0e-7081-7293-a4a5-102132435467",
      "listingVariantId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "listingId": "01914d0e-7081-7293-a4a5-102132435467",
      "saleAmount": 129900,
      "currency": "EUR",
      "baseAmount": 129900,
      "reference": {
        "amount": 129900,
        "isPreview": false,
        "source": "regular_price"
      },
      "buyerSeesAmount": 129900,
      "discountVisible": false,
      "activeSale": {
        "salePrice": 129900,
        "frozenReference": 0,
        "regularPrice": 129900,
        "discountVisible": false,
        "state": "live",
        "saleEndsAt": "2026-09-10T09:24:11Z"
      },
      "pill": "Pill",
      "pause": {
        "reason": "base_drop_seller",
        "baseAmount": 129900,
        "pausedAt": "2026-09-10T09:24:11Z"
      }
    }
  ],
  "activityTrail": {
    "items": [
      {
        "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
        "kind": "Kind",
        "listingVariantId": "01914d0e-7081-7293-a4a5-102132435467",
        "detail": {},
        "actorKind": "Actor kind",
        "occurredAt": "2026-09-10T09:24:11Z",
        "recordedAt": "2026-09-10T09:24:11Z",
        "traceId": "Trace id"
      }
    ],
    "_metadata": {
      "limit": 20,
      "hasMore": true,
      "nextCursor": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "prevCursor": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "totalCount": 129900
    }
  }
}
read#
GET/rest/v1/seller/stores/{storeId}/promotions/coupons/{couponId}promotions:readCoupon detail

Returns a coupon's configuration plus its usage counters (`timesUsed` / `totalUses`). Realized redemption statistics are served separately by svc-purchase (`GET /rest/v1/purchase/stores/{storeId}/coupons/{couponId}/redemptions`).

Requires

promotions:read

Path parameters

  • storeIdstring · uuidrequired
  • couponIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • issuerstringOne of: store · platform
  • codestring
  • descriptionstring
  • targetstringOne of: items · whole_order · delivery
  • discountobject
    • kindstringOne of: percent · fixed
    • percentinteger
    • capAmountinteger
    • fixedAmountinteger
    • currencystring
  • minPurchaseAmountinteger
  • totalUsesinteger
  • timesUsedinteger
  • validFromstring · date-time
  • validUntilstring · date-time
  • statusstringOne of: scheduled · active · expired · deactivated
  • deactivatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time
  • eligibleVariantsarray<object>
    • listingVariantIdstring · uuid
    • listingIdstring · uuid
  • deliveryScopesarray<object>
    • channelTypestring
    • lockerProviderCodestring

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/promotions/coupons/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "storeId": "01914d0e-8192-73a4-b5b6-213243546578",
  "issuer": "store",
  "code": "Code",
  "description": "Description",
  "target": "items",
  "discount": {
    "kind": "percent",
    "percent": 0,
    "capAmount": 129900,
    "fixedAmount": 129900,
    "currency": "EUR"
  },
  "minPurchaseAmount": 129900,
  "totalUses": 129900,
  "timesUsed": 0,
  "validFrom": "2026-09-10T09:24:11Z",
  "validUntil": "2026-09-10T09:24:11Z",
  "status": "scheduled",
  "deactivatedAt": "2026-09-10T09:24:11Z",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "eligibleVariants": [
    {
      "listingVariantId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "listingId": "01914d0e-6f70-7182-9394-0f1021324356"
    }
  ],
  "deliveryScopes": [
    {
      "channelType": "Channel type",
      "lockerProviderCode": "Locker provider code"
    }
  ]
}
read#
GET/rest/v1/seller/stores/{storeId}/listings/{listingId}/promotionspromotions:readList the promotions on a listing

Listing Promotions panel (J3.19). Returns the promotions intersecting a single listing — Active or Scheduled sales whose lines fall on the listing's variants, items-coupons eligible on those variants, and whole-order (store-wide) coupons…

Requires

promotions:read

Path parameters

  • storeIdstring · uuidrequired
  • listingIdstring · uuidrequired

Query parameters

  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountboolean

Response · 200

  • itemsarray<object>
    • promotionIdstring · uuid
    • kindstringOne of: sale · coupon
    • namestring
    • statusstring
    • startAtstring · date-time
    • endAtstring · date-time
    • variantScopeobjectCovered variants, or "All variants". `variantLabels` names each covered variant by its option-values label ("Black · 256GB"), or by the listing title for the sole variant of a single-version listing.
    • impactobjectCents-only price impact for a sale; the configured discount for a coupon
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/listings/01914d0e-7081-7293-a4a5-102132435467/promotions
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "promotionId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "kind": "sale",
      "name": "Name",
      "status": "Status",
      "startAt": "2026-09-10T09:24:11Z",
      "endAt": "2026-09-10T09:24:11Z",
      "variantScope": {
        "label": "Label",
        "coversAll": false,
        "variantLabels": [
          "Variant labels"
        ]
      },
      "impact": {}
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "prevCursor": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "totalCount": 129900
  }
}
read#

Seller Promotions — Sales 8 operations

POST/rest/v1/seller/stores/{storeId}/promotions/salespromotions:read_writeCreate draft sale

Opens a new sale in Draft for the store. Inert until scheduled.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • internalNamestringrequiredSeller-facing internal name for the sale

Response · 201

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/promotions/sales
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "internalName": "Spring clearance"
}
jsonResponse · 201
{
  "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "storeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "listingVariantId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "listingId": "01914d0e-8192-73a4-b5b6-213243546578",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PUT/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}promotions:read_writeSave draft sale

Saves a draft sale configuration (internal name + tentative window). Draft only — rejected once the sale is scheduled or active. The tentative window is echoed on read so the wizard can resume; the authoritative window is fixed at schedule…

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequired

Request body · application/json

  • internalNamestringrequiredSeller-facing internal name for the sale
  • startsAtstring · date-timeTentative window start (ISO 8601; draft-only, may be null while not yet picked). Echoed on read so the wizard can resume; the authoritative window is fixed at schedule time.
  • endsAtstring · date-timeTentative window end (ISO 8601; draft-only, may be null while not yet picked). Echoed on read so the wizard can resume; the authoritative window is fixed at schedule time.

Response · 200

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/seller/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/promotions/sales/01914d0e-4d5e-7f60-b172-8d9e0f102134
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "internalName": "Spring clearance",
  "startsAt": "2026-09-01T00:00:00Z",
  "endsAt": "2026-09-08T00:00:00Z"
}
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "storeId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "listingVariantId": "01914d0e-92a3-74b5-86c7-324354657689",
      "listingId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}/schedulepromotions:read_writeSchedule sale

Moves a draft sale to Scheduled by fixing its window. Validates the window and conflicts; freezes nothing.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequired

Request body · application/json

  • startsAtstring · date-timerequiredWindow start (ISO 8601)
  • endsAtstring · date-timerequiredWindow end (ISO 8601, must follow start)

Response · 200

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/promotions/sales/01914d0e-a3b4-75c6-97d8-43546576879a/schedule
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "startsAt": "2026-09-01T00:00:00Z",
  "endsAt": "2026-09-08T00:00:00Z"
}
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "storeId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "listingVariantId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "listingId": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}/variantspromotions:read_writeAdd sale variants

Adds one or more discounted lines to a sale. Lines joined onto a live sale are conflict-checked.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequired

Request body · application/json

  • variantsarray<object>requiredLines to add to the sale
    • listingVariantIdstring · uuidrequiredListing Variant to discount
    • listingIdstring · uuidrequiredParent listing of the variant
    • saleAmountintegerDiscounted price in minor units (cents). Null/omitted parks an unpriced line — allowed only while the sale is a Draft.

Response · 200

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/promotions/sales/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/variants
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "variants": [
    {
      "listingVariantId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "listingId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "saleAmount": 1999
    }
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "storeId": "01914d0e-7081-7293-a4a5-102132435467",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "listingVariantId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "listingId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
DELETE/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}/variants/{lineId}promotions:read_writeRemove sale variant

Removes a line from a sale. A sale must always keep at least one line.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequired
  • lineIdstring · uuidrequired

Response · 200

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/promotions/sales/01914d0e-7081-7293-a4a5-102132435467/variants/01914d0e-6f70-7182-9394-0f1021324356
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "storeId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "listingVariantId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "listingId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}/variants/{lineId}/change-pricepromotions:read_writeChange sale variant price

Changes a sale line's discounted price. While Active the buyer-effective price change is published.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequired
  • lineIdstring · uuidrequired

Request body · application/json

  • saleAmountintegerrequiredNew discounted price in minor units (cents)

Response · 200

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/promotions/sales/01914d0e-4d5e-7f60-b172-8d9e0f102134/variants/01914d0e-7081-7293-a4a5-102132435467/change-price
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "saleAmount": 1799
}
jsonResponse · 200
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "storeId": "01914d0e-8192-73a4-b5b6-213243546578",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "listingVariantId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "listingId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}/extendpromotions:read_writeExtend sale

Extends a scheduled or active sale's end date. Never shortens.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequired

Request body · application/json

  • endsAtstring · date-timerequiredNew window end (ISO 8601, must be later than the current end)

Response · 200

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/promotions/sales/01914d0e-5e6f-7071-8283-9e0f10213245/extend
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "endsAt": "2026-09-15T00:00:00Z"
}
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "storeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "listingVariantId": "01914d0e-92a3-74b5-86c7-324354657689",
      "listingId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/seller/stores/{storeId}/promotions/sales/{promotionId}/cancelpromotions:read_writeCancel sale

Cancels a scheduled or active sale — immediate and terminal. An active cancel reverts every live line to base.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • promotionIdstring · uuidrequired

Response · 200

  • idstring · uuidSale identifier
  • storeIdstring · uuidOwning store identifier
  • issuerstringWho issued the saleOne of: store · platform
  • internalNamestringSeller-facing internal name
  • statusstringSale lifecycle statusOne of: draft · scheduled · active · ended · cancelled
  • startsAtstring · date-timeWindow start. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • endsAtstring · date-timeWindow end. Tentative while Draft (echoed from the saved draft, may be null); authoritative once Scheduled.
  • activatedAtstring · date-timeInstant the reconciler activated the sale
  • endedAtstring · date-time
  • cancelledAtstring · date-time
  • variantsarray<object>Discounted sale lines
    • idstring · uuidSale line identifier
    • listingVariantIdstring · uuidDiscounted Listing Variant
    • listingIdstring · uuidParent listing of the variant
    • saleAmountintegerDiscounted price in cents. Null while an unpriced Draft line — a non-draft sale has every line priced.
    • currencystringISO 4217 currency code
    • frozenReferenceAmountintegerFrozen Omnibus reference price in cents (null until frozen at activation)
    • frozenReferenceSourcestringProvenance of the frozen 30-day reference (heuristic; see the design doc)One of: regular_price · promo_price
    • referenceFrozenAtstring · date-time
    • discountVisiblebooleanWhether the sale shows a struck reference (sale strictly below reference)
    • pausedbooleanWhether the line is auto-paused (base dropped to/below sale)
    • pausedAtstring · date-time
    • pauseReasonstringWhy the line was auto-pausedOne of: base_drop_seller · base_drop_cms
    • pausedBaseAmountintegerBase price in cents that triggered the pause
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/promotions/sales/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/cancel
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-8192-73a4-b5b6-213243546578",
  "storeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "issuer": "store",
  "internalName": "Spring clearance",
  "status": "draft",
  "startsAt": "2026-09-10T09:24:11Z",
  "endsAt": "2026-09-10T09:24:11Z",
  "activatedAt": "2026-09-10T09:24:11Z",
  "endedAt": "2026-09-10T09:24:11Z",
  "cancelledAt": "2026-09-10T09:24:11Z",
  "variants": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "listingVariantId": "01914d0e-7081-7293-a4a5-102132435467",
      "listingId": "01914d0e-8192-73a4-b5b6-213243546578",
      "saleAmount": 1999,
      "currency": "EUR",
      "frozenReferenceAmount": 129900,
      "frozenReferenceSource": "regular_price",
      "referenceFrozenAt": "2026-09-10T09:24:11Z",
      "discountVisible": false,
      "paused": false,
      "pausedAt": "2026-09-10T09:24:11Z",
      "pauseReason": "base_drop_seller",
      "pausedBaseAmount": 129900,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#

Seller Coupons 3 operations

POST/rest/v1/seller/stores/{storeId}/promotions/couponspromotions:read_writeCreate coupon

Issues a store coupon. It opens Active when already within its validity window, otherwise Scheduled.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • codestringrequiredCoupon code buyers enter at checkout
  • descriptionstring
  • targetstringrequiredWhat the discount applies toOne of: items · whole_order · delivery
  • discountobjectrequiredA coupon's discount configuration. Light structural bounds only — the aggregate is the authority on coherence (percent∈[1,100] with an optional percent-only cap; fixed≥1 with a currency).
    • kindstringrequiredOne of: percent · fixed
    • percentintegerPercent value (1-100), for the percent kind
    • capAmountintegerOptional cap in cents on a percent discount
    • fixedAmountintegerFixed amount in cents, for the fixed kind
    • currencystringISO 4217 currency, required for the fixed kind
  • minPurchaseAmountintegerMinimum items subtotal in cents to qualify
  • totalUsesintegerGlobal usage limit (null = unlimited)
  • validFromstring · date-timerequiredValidity window start (ISO 8601)
  • validUntilstring · date-timerequiredValidity window end (ISO 8601)
  • eligibleVariantsarray<object>Items-target eligibility (required for the items target)
    • listingIdstring · uuidrequiredParent listing id
    • listingVariantIdstring · uuidrequiredEligible listing variant id
  • deliveryChannelsarray<object>Delivery-target scope (required for the delivery target)
    • channelTypestringrequiredDelivery channel type offered by the store
    • lockerProviderCodestringOptional locker-provider narrowing (carrier network code)

Response · 201

  • idstring · uuid
  • storeIdstring · uuid
  • issuerstringOne of: store · platform
  • codestring
  • descriptionstring
  • targetstringOne of: items · whole_order · delivery
  • discountobject
    • kindstringOne of: percent · fixed
    • percentinteger
    • capAmountinteger
    • fixedAmountinteger
    • currencystring
  • minPurchaseAmountinteger
  • totalUsesinteger
  • timesUsedinteger
  • validFromstring · date-time
  • validUntilstring · date-time
  • statusstringOne of: scheduled · active · expired · deactivated
  • deactivatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time
  • eligibleVariantsarray<object>
    • idstring · uuid
    • listingIdstring · uuid
    • listingVariantIdstring · uuid
  • deliveryScopesarray<object>
    • idstring · uuid
    • channelTypestring
    • lockerProviderCodestring

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-6f70-7182-9394-0f1021324356/promotions/coupons
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "code": "SPRING20",
  "description": "Spring sale",
  "target": "whole_order",
  "discount": {
    "kind": "percent",
    "percent": 15,
    "capAmount": 2000,
    "fixedAmount": 500,
    "currency": "EUR"
  },
  "minPurchaseAmount": 3000,
  "totalUses": 100,
  "validFrom": "2026-09-10T09:24:11Z",
  "validUntil": "2026-09-10T09:24:11Z",
  "eligibleVariants": [
    {
      "listingId": "01914d0e-92a3-74b5-86c7-324354657689",
      "listingVariantId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc"
    }
  ],
  "deliveryChannels": [
    {
      "channelType": "locker",
      "lockerProviderCode": "omniva"
    }
  ]
}
jsonResponse · 201
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "storeId": "01914d0e-8192-73a4-b5b6-213243546578",
  "issuer": "store",
  "code": "Code",
  "description": "Description",
  "target": "items",
  "discount": {
    "kind": "percent",
    "percent": 0,
    "capAmount": 129900,
    "fixedAmount": 129900,
    "currency": "EUR"
  },
  "minPurchaseAmount": 129900,
  "totalUses": 129900,
  "timesUsed": 0,
  "validFrom": "2026-09-10T09:24:11Z",
  "validUntil": "2026-09-10T09:24:11Z",
  "status": "scheduled",
  "deactivatedAt": "2026-09-10T09:24:11Z",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "eligibleVariants": [
    {
      "id": "01914d0e-6f70-7182-9394-0f1021324356",
      "listingId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "listingVariantId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01"
    }
  ],
  "deliveryScopes": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "channelType": "Channel type",
      "lockerProviderCode": "Locker provider code"
    }
  ]
}
write#
PATCH/rest/v1/seller/stores/{storeId}/promotions/coupons/{couponId}promotions:read_writeRevise coupon

Revises a coupon. Only provided fields change. Core fields (`code`, `discount`) are locked once the coupon is Active — editing them then returns 422.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • couponIdstring · uuidrequired

Request body · application/json

  • codestringNew coupon code (core — editable only while Scheduled)
  • discountobjectA coupon's discount configuration. Light structural bounds only — the aggregate is the authority on coherence (percent∈[1,100] with an optional percent-only cap; fixed≥1 with a currency).
    • kindstringrequiredOne of: percent · fixed
    • percentintegerPercent value (1-100), for the percent kind
    • capAmountintegerOptional cap in cents on a percent discount
    • fixedAmountintegerFixed amount in cents, for the fixed kind
    • currencystringISO 4217 currency, required for the fixed kind
  • descriptionstring
  • minPurchaseAmountinteger
  • totalUsesinteger
  • validUntilstring · date-time
  • eligibleVariantsarray<object>
    • listingIdstring · uuidrequiredParent listing id
    • listingVariantIdstring · uuidrequiredEligible listing variant id
  • deliveryChannelsarray<object>
    • channelTypestringrequiredDelivery channel type offered by the store
    • lockerProviderCodestringOptional locker-provider narrowing (carrier network code)

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • issuerstringOne of: store · platform
  • codestring
  • descriptionstring
  • targetstringOne of: items · whole_order · delivery
  • discountobject
    • kindstringOne of: percent · fixed
    • percentinteger
    • capAmountinteger
    • fixedAmountinteger
    • currencystring
  • minPurchaseAmountinteger
  • totalUsesinteger
  • timesUsedinteger
  • validFromstring · date-time
  • validUntilstring · date-time
  • statusstringOne of: scheduled · active · expired · deactivated
  • deactivatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time
  • eligibleVariantsarray<object>
    • idstring · uuid
    • listingIdstring · uuid
    • listingVariantIdstring · uuid
  • deliveryScopesarray<object>
    • idstring · uuid
    • channelTypestring
    • lockerProviderCodestring

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-8192-73a4-b5b6-213243546578/promotions/coupons/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "code": "Code",
  "discount": {
    "kind": "percent",
    "percent": 15,
    "capAmount": 2000,
    "fixedAmount": 500,
    "currency": "EUR"
  },
  "description": "Description",
  "minPurchaseAmount": 129900,
  "totalUses": 129900,
  "validUntil": "2026-09-10T09:24:11Z",
  "eligibleVariants": [
    {
      "listingId": "01914d0e-7081-7293-a4a5-102132435467",
      "listingVariantId": "01914d0e-6f70-7182-9394-0f1021324356"
    }
  ],
  "deliveryChannels": [
    {
      "channelType": "locker",
      "lockerProviderCode": "omniva"
    }
  ]
}
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "storeId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "issuer": "store",
  "code": "Code",
  "description": "Description",
  "target": "items",
  "discount": {
    "kind": "percent",
    "percent": 0,
    "capAmount": 129900,
    "fixedAmount": 129900,
    "currency": "EUR"
  },
  "minPurchaseAmount": 129900,
  "totalUses": 129900,
  "timesUsed": 0,
  "validFrom": "2026-09-10T09:24:11Z",
  "validUntil": "2026-09-10T09:24:11Z",
  "status": "scheduled",
  "deactivatedAt": "2026-09-10T09:24:11Z",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "eligibleVariants": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "listingId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "listingVariantId": "01914d0e-b4c5-76d7-a8e9-546576879aab"
    }
  ],
  "deliveryScopes": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "channelType": "Channel type",
      "lockerProviderCode": "Locker provider code"
    }
  ]
}
write#
POST/rest/v1/seller/stores/{storeId}/promotions/coupons/{couponId}/deactivatepromotions:read_writeDeactivate coupon

Deactivates a live coupon — immediate and terminal. Past orders are unaffected and the code frees for reuse.

Requires

promotions:read_write

Path parameters

  • storeIdstring · uuidrequired
  • couponIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • storeIdstring · uuid
  • issuerstringOne of: store · platform
  • codestring
  • descriptionstring
  • targetstringOne of: items · whole_order · delivery
  • discountobject
    • kindstringOne of: percent · fixed
    • percentinteger
    • capAmountinteger
    • fixedAmountinteger
    • currencystring
  • minPurchaseAmountinteger
  • totalUsesinteger
  • timesUsedinteger
  • validFromstring · date-time
  • validUntilstring · date-time
  • statusstringOne of: scheduled · active · expired · deactivated
  • deactivatedAtstring · date-time
  • createdAtstring · date-time
  • updatedAtstring · date-time
  • eligibleVariantsarray<object>
    • idstring · uuid
    • listingIdstring · uuid
    • listingVariantIdstring · uuid
  • deliveryScopesarray<object>
    • idstring · uuid
    • channelTypestring
    • lockerProviderCodestring

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/promotions/coupons/01914d0e-6f70-7182-9394-0f1021324356/deactivate
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-6f70-7182-9394-0f1021324356",
  "storeId": "01914d0e-92a3-74b5-86c7-324354657689",
  "issuer": "store",
  "code": "Code",
  "description": "Description",
  "target": "items",
  "discount": {
    "kind": "percent",
    "percent": 0,
    "capAmount": 129900,
    "fixedAmount": 129900,
    "currency": "EUR"
  },
  "minPurchaseAmount": 129900,
  "totalUses": 129900,
  "timesUsed": 0,
  "validFrom": "2026-09-10T09:24:11Z",
  "validUntil": "2026-09-10T09:24:11Z",
  "status": "scheduled",
  "deactivatedAt": "2026-09-10T09:24:11Z",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "eligibleVariants": [
    {
      "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "listingId": "01914d0e-92a3-74b5-86c7-324354657689",
      "listingVariantId": "01914d0e-4d5e-7f60-b172-8d9e0f102134"
    }
  ],
  "deliveryScopes": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "channelType": "Channel type",
      "lockerProviderCode": "Locker provider code"
    }
  ]
}
write#

Seller Stock — Warehouses 4 operations

POST/rest/v1/seller/stores/{storeId}/stock/warehousesstock:read_writeCreate warehouse

Creates a warehouse for the store's Stockpile Account. The first warehouse provisions the account. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • namestringrequiredWarehouse display name
  • codestringHuman-readable warehouse code, unique per account
  • typestringWarehouse type
  • addressobjectWarehouse address

Response · 201

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/stock/warehouses
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Main Warehouse",
  "code": "Code",
  "type": "Type",
  "address": {}
}
write#
GET/rest/v1/seller/stores/{storeId}/stock/warehousesstock:readList warehouses

Returns a paginated list of the store account's warehouses. Requires the `stock:read` capability. A store with no Stockpile Account yet returns an empty list.

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • statusstring
  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountboolean

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/stock/warehouses
Authorization: Bearer $TOKEN
read#
PATCH/rest/v1/seller/stores/{storeId}/stock/warehouses/{warehouseId}stock:read_writeConfigure warehouse

Updates the name and/or address of a warehouse. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • warehouseIdstring · uuidrequired

Request body · application/json

  • namestringWarehouse display name
  • addressobjectWarehouse address

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/stock/warehouses/01914d0e-6f70-7182-9394-0f1021324356
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Name",
  "address": {}
}
write#
PATCH/rest/v1/seller/stores/{storeId}/stock/warehouses/{warehouseId}/statusstock:read_writeChange warehouse status

Transitions a warehouse to a new status. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • warehouseIdstring · uuidrequired

Request body · application/json

  • statusstringrequiredTarget warehouse status

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/stock/warehouses/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/status
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "status": "SUSPENDED"
}
write#

Seller Stock — Stock Items 6 operations

POST/rest/v1/seller/stores/{storeId}/stock/stock-itemsstock:read_writeRegister stock item

Registers a new stock item for the store account. SKU must be unique per account. Requires the `stock:read_write` capability. A store with no Stockpile Account yet returns 422 "Create a warehouse first."

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • skustringrequiredHuman-readable SKU
  • namestringrequiredHuman-readable item label
  • externalReferencestringOpaque link to external system

Response · 201

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/stock/stock-items
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "sku": "WIDGET-001",
  "name": "Blue Widget (Large)",
  "externalReference": "External reference"
}
write#
GET/rest/v1/seller/stores/{storeId}/stock/stock-itemsstock:readList stock items

Returns a paginated list of the store account's stock items, optionally filtered by SKU substring and status. Requires the `stock:read` capability.

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • skustring
  • statusstring
  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountboolean

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/stock/stock-items
Authorization: Bearer $TOKEN
read#
GET/rest/v1/seller/stores/{storeId}/stock/stock-items/countsstock:readGet stock item availability counts

Returns availability counts (in-stock, low-stock, out-of-stock) for the store account's stock items, optionally scoped to a warehouse and status. Requires the `stock:read` capability.

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • warehouseIdstring
  • statusstring
  • lowStockThresholdinteger

Response · 200

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/stock/stock-items/counts
Authorization: Bearer $TOKEN
read#
POST/rest/v1/seller/stores/{storeId}/stock/stock-items/generate-skusstock:read_writeGenerate SKUs in bulk

Generates a batch of unique SKUs for the store account, with an optional prefix. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • countintegerrequiredNumber of SKUs to generate
  • prefixstringOptional SKU prefix

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/stock/stock-items/generate-skus
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "count": 5,
  "prefix": "Prefix"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/stock/stock-items/{stockItemId}stock:read_writeConfigure stock item

Updates the label and/or external reference of a stock item. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • stockItemIdstring · uuidrequired

Request body · application/json

  • namestringHuman-readable item label
  • externalReferencestringOpaque link to external system

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/stock/stock-items/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Name",
  "externalReference": "External reference"
}
write#
PATCH/rest/v1/seller/stores/{storeId}/stock/stock-items/{stockItemId}/statusstock:read_writeChange stock item status

Transitions a stock item to a new status. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • stockItemIdstring · uuidrequired

Request body · application/json

  • statusstringrequiredTarget stock item status

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
PATCH /rest/v1/seller/stores/01914d0e-6f70-7182-9394-0f1021324356/stock/stock-items/01914d0e-a3b4-75c6-97d8-43546576879a/status
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "status": "DISCONTINUED"
}
write#

Seller Stock — Inventory 2 operations

GET/rest/v1/seller/stores/{storeId}/stock/inventorystock:readGet inventory positions

Returns inventory positions for the store account, optionally filtered by stock item and/or warehouse. Requires the `stock:read` capability.

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • stockItemIdstring · uuid
  • warehouseIdstring · uuid

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/stock/inventory
Authorization: Bearer $TOKEN
read#
POST/rest/v1/seller/stores/{storeId}/stock/inventory/set-balancestock:read_writeSet stock balance

Sets the absolute on-hand quantity for a stock item at a warehouse. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • stockItemIdstringrequiredStock item ID
  • warehouseIdstringrequiredWarehouse ID
  • quantityintegerrequiredDesired on-hand quantity (absolute value)

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/stock/inventory/set-balance
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "stockItemId": "Stock item id",
  "warehouseId": "Warehouse id",
  "quantity": 100
}
write#

Seller Stock — Movements 1 operation

GET/rest/v1/seller/stores/{storeId}/stock/movementsstock:readList stock movements

Returns a paginated stock movement ledger for the store account, optionally filtered by stock item, warehouse, and since-timestamp. Requires the `stock:read` capability.

Requires

stock:read

Path parameters

  • storeIdstring · uuidrequired

Query parameters

  • stockItemIdstring · uuid
  • warehouseIdstring · uuid
  • sincestringInclusive lower bound: only movements that occurred at or after it. A date (YYYY-MM-DD) means midnight at the start of that day in the platform time zone (Europe/Vilnius); a date-time (YYYY-MM-DDTHH:MM[:SS][.fraction][Z|±HH:MM]) names its…
  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountboolean

Response · 200

No content.

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/stock/movements
Authorization: Bearer $TOKEN
read#

Seller Stock — Adjustments 2 operations

POST/rest/v1/seller/stores/{storeId}/stock/adjustmentsstock:read_writeCreate an adjustment

Creates a draft inventory adjustment with one or more lines for a warehouse. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • warehouseIdstringrequiredWarehouse ID
  • reasonCodestringrequiredReason code
  • linesarray<object>required
    • stockItemIdstringrequiredStock item ID
    • quantityintegerrequiredSigned quantity delta
    • conditionstringrequiredStock condition
    • reasonCodestringPer-line reason code override
    • expectedOnHandintegerOn-hand quantity the line was based on, negative included (on-hand has no floor). When set, posting the adjustment answers 409 if the stock position's on-hand changed since, and nothing is applied; the line must then be the only one for…
  • notesstringOptional notes

Response · 201

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-92a3-74b5-86c7-324354657689/stock/adjustments
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "warehouseId": "Warehouse id",
  "reasonCode": "DAMAGE",
  "lines": [
    {
      "stockItemId": "Stock item id",
      "quantity": 0,
      "condition": "AVAILABLE",
      "reasonCode": "Reason code",
      "expectedOnHand": 12
    }
  ],
  "notes": "Notes"
}
write#
POST/rest/v1/seller/stores/{storeId}/stock/adjustments/{adjustmentId}/poststock:read_writePost an adjustment

Posts a draft adjustment, applying it to inventory and creating stock movements. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • adjustmentIdstringrequired

Response · 200

No content.

Errors

401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/stock/adjustments/Adjustment id/post
Authorization: Bearer $TOKEN
write#

Seller Stock — Transfers 4 operations

POST/rest/v1/seller/stores/{storeId}/stock/transfersstock:read_writeCreate a transfer

Creates an inter-warehouse transfer with one or more lines. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired

Request body · application/json

  • fromWarehouseIdstringrequiredSource warehouse ID
  • toWarehouseIdstringrequiredDestination warehouse ID
  • linesarray<object>required
    • stockItemIdstringrequiredStock item ID
    • quantityintegerrequiredQuantity to transfer
    • conditionstringrequiredStock condition

Response · 201

No content.

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-5e6f-7071-8283-9e0f10213245/stock/transfers
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "fromWarehouseId": "From warehouse id",
  "toWarehouseId": "To warehouse id",
  "lines": [
    {
      "stockItemId": "Stock item id",
      "quantity": 0,
      "condition": "AVAILABLE"
    }
  ]
}
write#
POST/rest/v1/seller/stores/{storeId}/stock/transfers/{transferId}/dispatchstock:read_writeDispatch a transfer

Dispatches a transfer from its source warehouse. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • transferIdstringrequired

Response · 200

No content.

Errors

401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/stock/transfers/Transfer id/dispatch
Authorization: Bearer $TOKEN
write#
POST/rest/v1/seller/stores/{storeId}/stock/transfers/{transferId}/receivestock:read_writeReceive a transfer

Receives an in-transit transfer at its destination warehouse. Repeating the call on a transfer that is already received succeeds and changes nothing, so a retry after a lost response is safe. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • transferIdstringrequired

Response · 200

No content.

Errors

401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-6f70-7182-9394-0f1021324356/stock/transfers/Transfer id/receive
Authorization: Bearer $TOKEN
write#
POST/rest/v1/seller/stores/{storeId}/stock/transfers/{transferId}/cancelstock:read_writeCancel a transfer

Cancels a draft transfer. Repeating the call on a transfer that is already cancelled succeeds and changes nothing, so a retry after a lost response is safe. Requires the `stock:read_write` capability.

Requires

stock:read_write

Path parameters

  • storeIdstring · uuidrequired
  • transferIdstringrequired

Response · 200

No content.

Errors

401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/stores/01914d0e-7081-7293-a4a5-102132435467/stock/transfers/Transfer id/cancel
Authorization: Bearer $TOKEN
write#

Customer Cart 4 operations

POST/rest/v1/customer/cart/itemsauthenticatedAdd item to cart

Adds a listing to the customer's cart. If the listing already exists, increments quantity. Creates the cart automatically on first use.

Requires

authenticated

Request body · application/json

  • listingIdstring · uuidrequiredID of the Listing Variant to add
  • quantityintegerNumber of units to add

Response · 201

  • idstring · uuidrequiredCart ID (empty string if cart does not exist yet)
  • customerIdstring · uuidrequiredCustomer ID
  • storeGroupsarray<object>requiredItems grouped by store
    • storeIdstring · uuidrequiredStore ID (group identity)
    • itemsarray<object>requiredItems from this store
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
    • storeNamestringStore display name
    • subtotalAmountintegerGroup subtotal in cents
    • subtotalCurrencystringISO 4217 currency of `subtotalAmount`.
    • checkoutDisabledbooleanTrue when every item in the group is unavailable, so the group cannot be taken to checkout.
  • totalItemCountintegerrequiredTotal distinct line items across all stores
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired
  • totalAmountintegerCart total in cents. Null until every item has a resolved price.
  • totalCurrencystringISO 4217 currency of `totalAmount`.

Errors

401 · 403 · 422 · 503 — See the error reference

httpRequest
POST /rest/v1/customer/cart/items
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "listingId": "01914d0e-6f70-7182-9394-0f1021324356",
  "quantity": 1
}
jsonResponse · 201
{
  "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "customerId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "storeGroups": [
    {
      "storeId": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "items": [
        {
          "id": "01914d0e-8192-73a4-b5b6-213243546578",
          "listingVariantId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
          "storeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
          "quantity": 0,
          "createdAt": "2026-09-10T09:24:11Z",
          "updatedAt": "2026-09-10T09:24:11Z",
          "title": "Title",
          "priceAmount": 129900,
          "priceCurrency": "EUR",
          "imageUrl": "Image url",
          "variantDescription": "256GB, Red",
          "productId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
          "isAvailable": false
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z",
      "storeName": "Store name",
      "subtotalAmount": 129900,
      "subtotalCurrency": "EUR",
      "checkoutDisabled": false
    }
  ],
  "totalItemCount": 129900,
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "totalAmount": 129900,
  "totalCurrency": "EUR"
}
write#
PATCH/rest/v1/customer/cart/items/{itemId}authenticatedChange cart item quantity

Updates the quantity of an existing cart item.

Requires

authenticated

Path parameters

  • itemIdstring · uuidrequiredCart item ID

Request body · application/json

  • quantityintegerrequiredNew quantity for the cart item

Response · 200

  • idstring · uuidrequiredCart ID (empty string if cart does not exist yet)
  • customerIdstring · uuidrequiredCustomer ID
  • storeGroupsarray<object>requiredItems grouped by store
    • storeIdstring · uuidrequiredStore ID (group identity)
    • itemsarray<object>requiredItems from this store
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
    • storeNamestringStore display name
    • subtotalAmountintegerGroup subtotal in cents
    • subtotalCurrencystringISO 4217 currency of `subtotalAmount`.
    • checkoutDisabledbooleanTrue when every item in the group is unavailable, so the group cannot be taken to checkout.
  • totalItemCountintegerrequiredTotal distinct line items across all stores
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired
  • totalAmountintegerCart total in cents. Null until every item has a resolved price.
  • totalCurrencystringISO 4217 currency of `totalAmount`.

Errors

401 · 403 · 404 · 422 · 503 — See the error reference

httpRequest
PATCH /rest/v1/customer/cart/items/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "quantity": 0
}
jsonResponse · 200
{
  "id": "01914d0e-8192-73a4-b5b6-213243546578",
  "customerId": "01914d0e-8192-73a4-b5b6-213243546578",
  "storeGroups": [
    {
      "storeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "items": [
        {
          "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
          "listingVariantId": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "storeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "quantity": 0,
          "createdAt": "2026-09-10T09:24:11Z",
          "updatedAt": "2026-09-10T09:24:11Z",
          "title": "Title",
          "priceAmount": 129900,
          "priceCurrency": "EUR",
          "imageUrl": "Image url",
          "variantDescription": "256GB, Red",
          "productId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "isAvailable": false
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z",
      "storeName": "Store name",
      "subtotalAmount": 129900,
      "subtotalCurrency": "EUR",
      "checkoutDisabled": false
    }
  ],
  "totalItemCount": 129900,
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "totalAmount": 129900,
  "totalCurrency": "EUR"
}
write#
DELETE/rest/v1/customer/cart/items/{itemId}authenticatedRemove cart item

Removes an item from the cart. Empty seller groups and the cart itself are cleaned up automatically.

Requires

authenticated

Path parameters

  • itemIdstring · uuidrequiredCart item ID

Response · 200

  • idstring · uuidrequiredCart ID (empty string if cart does not exist yet)
  • customerIdstring · uuidrequiredCustomer ID
  • storeGroupsarray<object>requiredItems grouped by store
    • storeIdstring · uuidrequiredStore ID (group identity)
    • itemsarray<object>requiredItems from this store
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
    • storeNamestringStore display name
    • subtotalAmountintegerGroup subtotal in cents
    • subtotalCurrencystringISO 4217 currency of `subtotalAmount`.
    • checkoutDisabledbooleanTrue when every item in the group is unavailable, so the group cannot be taken to checkout.
  • totalItemCountintegerrequiredTotal distinct line items across all stores
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired
  • totalAmountintegerCart total in cents. Null until every item has a resolved price.
  • totalCurrencystringISO 4217 currency of `totalAmount`.

Errors

401 · 403 · 404 · 503 — See the error reference

httpRequest
DELETE /rest/v1/customer/cart/items/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "customerId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "storeGroups": [
    {
      "storeId": "01914d0e-7081-7293-a4a5-102132435467",
      "items": [
        {
          "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
          "listingVariantId": "01914d0e-5e6f-7071-8283-9e0f10213245",
          "storeId": "01914d0e-5e6f-7071-8283-9e0f10213245",
          "quantity": 0,
          "createdAt": "2026-09-10T09:24:11Z",
          "updatedAt": "2026-09-10T09:24:11Z",
          "title": "Title",
          "priceAmount": 129900,
          "priceCurrency": "EUR",
          "imageUrl": "Image url",
          "variantDescription": "256GB, Red",
          "productId": "01914d0e-7081-7293-a4a5-102132435467",
          "isAvailable": false
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z",
      "storeName": "Store name",
      "subtotalAmount": 129900,
      "subtotalCurrency": "EUR",
      "checkoutDisabled": false
    }
  ],
  "totalItemCount": 129900,
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "totalAmount": 129900,
  "totalCurrency": "EUR"
}
write#
GET/rest/v1/customer/cartauthenticatedGet customer cart

Returns the customer's cart with all items grouped by seller. Returns an empty cart structure if no cart exists.

Requires

authenticated

Response · 200

  • idstring · uuidrequiredCart ID (empty string if cart does not exist yet)
  • customerIdstring · uuidrequiredCustomer ID
  • storeGroupsarray<object>requiredItems grouped by store
    • storeIdstring · uuidrequiredStore ID (group identity)
    • itemsarray<object>requiredItems from this store
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired
    • storeNamestringStore display name
    • subtotalAmountintegerGroup subtotal in cents
    • subtotalCurrencystringISO 4217 currency of `subtotalAmount`.
    • checkoutDisabledbooleanTrue when every item in the group is unavailable, so the group cannot be taken to checkout.
  • totalItemCountintegerrequiredTotal distinct line items across all stores
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired
  • totalAmountintegerCart total in cents. Null until every item has a resolved price.
  • totalCurrencystringISO 4217 currency of `totalAmount`.

Errors

401 · 403 · 503 — See the error reference

httpRequest
GET /rest/v1/customer/cart
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "customerId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "storeGroups": [
    {
      "storeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "items": [
        {
          "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
          "listingVariantId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "storeId": "01914d0e-6f70-7182-9394-0f1021324356",
          "quantity": 0,
          "createdAt": "2026-09-10T09:24:11Z",
          "updatedAt": "2026-09-10T09:24:11Z",
          "title": "Title",
          "priceAmount": 129900,
          "priceCurrency": "EUR",
          "imageUrl": "Image url",
          "variantDescription": "256GB, Red",
          "productId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
          "isAvailable": false
        }
      ],
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z",
      "storeName": "Store name",
      "subtotalAmount": 129900,
      "subtotalCurrency": "EUR",
      "checkoutDisabled": false
    }
  ],
  "totalItemCount": 129900,
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z",
  "totalAmount": 129900,
  "totalCurrency": "EUR"
}
read#

Checkout 9 operations

POST/rest/v1/customer/checkoutauthenticatedCheckout — create order from cart

Converts a cart seller group directly into an order in a single call, without a PurchaseIntent draft. Creates the order, commits stock, and initiates a payment session. For delivery, `deliveryAddressId` is required; for pickup…

Requires

authenticated

Request body · application/json

  • sellerGroupIdstring · uuidrequiredSeller group (store) ID from the cart
  • fulfillmentMethodstringrequiredFulfillment methodOne of: delivery · pickup
  • deliveryAddressIdstring · uuidDelivery address ID (required when fulfillmentMethod is delivery)
  • pickupLocationIdstring · uuidPickup location ID (required when fulfillmentMethod is pickup)
  • contactPhonestringrequiredContact phone number
  • contactEmailstring · emailrequiredContact email address
  • recipientNamestringDelivery recipient name (courier-facing), an order-level contact attribute. Optional; the address book carries no recipient.
  • customerNotestringOptional note from the customer (max 500 characters)
  • paymentMethodKeystringrequiredPayment method key
  • paymentFlowstringProvider-specific payment flow type
  • paymentCountryCodestringISO 3166-1 alpha-2 country code for payment
  • platformstringClient platform initiating checkout (web or mobile)One of: web · mobile
  • localestringThe storefront language the customer checks out in. Stored on the order, so the customer's letters about it are written in this language. Optional; omit or send null when the client has no active locale. A value outside the set is a 422…One of: en · lt · lv · et

Response · 201

  • orderIdstring · uuidrequiredOrder ID
  • orderReferencestringrequiredHuman-readable order reference
  • statusstringrequiredOrder status
  • paymentRedirectUrlstringrequiredURL to redirect customer for payment
  • paymentIdstring · uuidrequiredPayment session ID
  • totalAmountintegerrequiredTotal order amount in cents
  • totalDeliveryCostintegerrequiredTotal delivery cost in cents
  • currencystringrequiredISO 4217 currency code
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/customer/checkout
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "sellerGroupId": "01914d0e-7081-7293-a4a5-102132435467",
  "fulfillmentMethod": "delivery",
  "deliveryAddressId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "pickupLocationId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "contactPhone": "+37061234567",
  "contactEmail": "seller@example.com",
  "recipientName": "Recipient name",
  "customerNote": "Customer note",
  "paymentMethodKey": "swedbank",
  "paymentFlow": "Payment flow",
  "paymentCountryCode": "LT",
  "platform": "web",
  "locale": "lt"
}
jsonResponse · 201
{
  "orderId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "orderReference": "MKT-2026-A3F9K2",
  "status": "new",
  "paymentRedirectUrl": "Payment redirect url",
  "paymentId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "totalAmount": 4998,
  "totalDeliveryCost": 0,
  "currency": "EUR",
  "createdAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/customer/purchase-intentsauthenticatedCreate purchase intent

Creates a new purchase intent from a cart seller group. Replaces any existing active draft for the same customer and store. The intent captures a price snapshot and starts a TTL countdown.

Requires

authenticated

Request body · application/json

  • sellerGroupIdstring · uuidrequiredStore (seller group) ID from the cart
  • localestringThe storefront language the customer checks out in. Carried to the order this intent confirms into, so the customer's letters about it are written in this language. Optional; omit or send null when the client has no active locale. A value…One of: en · lt · lv · et

Response · 201

  • idstring · uuidrequiredPurchase intent ID
  • statusstringrequiredCurrent statusOne of: draft · confirming · confirmed · expired
  • storeIdstring · uuidrequiredStore ID
  • currencystringrequiredCurrency code (ISO 4217)
  • expiresAtstring · date-timerequiredExpiration timestamp
  • fulfillmentMethodstringSelected fulfillment methodOne of: delivery · pickup · locker
  • deliveryAddressobjectDelivery address snapshot
  • pickupLocationobjectPickup location snapshot
  • lockerTerminalobjectSelected locker terminal snapshot (id, externalId, name, address, city, countryCode, carrierCode, carrierName)
  • contactobjectrequiredContact information
    • phonestringContact phone number
    • emailstringContact email address
    • recipientNamestringDelivery recipient name (courier-facing)
    • customerNotestringOptional customer note
  • itemsarray<object>requiredLine items
    • idstring · uuidrequiredItem ID
    • listingVariantIdstring · uuidrequiredListing variant ID
    • productVariantIdstring · uuidProduct variant ID (if linked to canonical catalog)
    • titlestringrequiredItem title at time of intent creation
    • imageUrlstringPrimary image URL
    • quantityintegerrequiredQuantity
    • unitPriceintegerrequiredUnit price in cents
    • lineSubtotalintegerrequiredLine subtotal (unitPrice * quantity) in cents
    • lineDiscountintegerrequiredLine discount in cents
    • lineTotalintegerrequiredLine total after discount in cents
  • shipmentGroupsarray<object>requiredShipment groups with available methods
    • idstring · uuidrequiredShipment group ID
    • locationIdstring · uuidrequiredOrigin location ID
    • locationNamestringOrigin location name
    • fulfillmentMethodstringrequiredFulfillment method for this groupOne of: delivery · pickup · locker
    • selectedMethodIdstring · uuidrequiredSelected shipping/locker method ID
    • selectedMethodNamestringrequiredSelected shipping/locker method name
    • carrierNamestringCarrier name
    • carrierCodestringCarrier registry code (locker groups)
    • deliveryCostintegerrequiredDelivery cost in cents
    • estimatedMinDaysintegerEstimated minimum delivery days
    • estimatedMaxDaysintegerEstimated maximum delivery days
    • isFreeDeliverybooleanrequiredWhether delivery is free
    • itemIdsarray<string>requiredIntent item IDs in this group
    • availableMethodsarray<object>requiredAvailable shipping methods
  • offeredChannelsarray<string>Channels the store offers for this checkout. Populated only on the GET read; mutation responses carry it empty (the frontend refetches).One of: delivery · pickup · locker
  • lockerOptionsarray<object>Locker methods offered for this checkout. Populated only on the GET read; mutation responses carry it empty.
  • couponobjectApplied coupon details (null when no coupon is applied). `discountAmount` is the realized items/whole-order discount in cents; `deliveryDiscountAmount` is the realized delivery-target discount in cents. `discountKind`/`discountValue` are…
    • codestringCoupon code
    • discountKindstringReserved — currently null
    • discountValueintegerReserved — currently null
    • discountAmountintegerRealized items/whole-order discount in cents
    • deliveryDiscountAmountintegerRealized delivery-target discount in cents
  • priceBreakdownobjectrequired
    • itemsSubtotalintegerrequiredSum of all line item subtotals in cents
    • totalDiscountintegerrequiredTotal items/whole-order discount amount in cents
    • totalDeliveryCostintegerrequiredTotal delivery cost in cents
    • deliveryDiscountintegerrequiredDelivery discount from a delivery-target coupon in cents
    • orderTotalintegerrequiredFinal order total in cents (itemsSubtotal - totalDiscount + totalDeliveryCost - deliveryDiscount)
  • createdAtstring · date-timerequiredCreated timestamp
  • updatedAtstring · date-timerequiredUpdated timestamp

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/customer/purchase-intents
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "sellerGroupId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "locale": "lt"
}
jsonResponse · 201
{
  "id": "01914d0e-7081-7293-a4a5-102132435467",
  "status": "draft",
  "storeId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "currency": "EUR",
  "expiresAt": "2026-09-10T09:24:11Z",
  "fulfillmentMethod": "delivery",
  "deliveryAddress": {},
  "pickupLocation": {},
  "lockerTerminal": {},
  "contact": {
    "phone": "Phone",
    "email": "Email",
    "recipientName": "Recipient name",
    "customerNote": "Customer note"
  },
  "items": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "listingVariantId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "productVariantId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "title": "Title",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 129900,
      "lineSubtotal": 129900,
      "lineDiscount": 0,
      "lineTotal": 129900
    }
  ],
  "shipmentGroups": [
    {
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "locationId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "locationName": "Location name",
      "fulfillmentMethod": "delivery",
      "selectedMethodId": "01914d0e-92a3-74b5-86c7-324354657689",
      "selectedMethodName": "Selected method name",
      "carrierName": "Carrier name",
      "carrierCode": "Carrier code",
      "deliveryCost": 0,
      "estimatedMinDays": 0,
      "estimatedMaxDays": 0,
      "isFreeDelivery": false,
      "itemIds": [
        "01914d0e-5e6f-7071-8283-9e0f10213245"
      ],
      "availableMethods": [
        {}
      ]
    }
  ],
  "offeredChannels": [
    "delivery"
  ],
  "lockerOptions": [
    {}
  ],
  "coupon": {
    "code": "Code",
    "discountKind": "Discount kind",
    "discountValue": 0,
    "discountAmount": 129900,
    "deliveryDiscountAmount": 129900
  },
  "priceBreakdown": {
    "itemsSubtotal": 129900,
    "totalDiscount": 129900,
    "totalDeliveryCost": 129900,
    "deliveryDiscount": 0,
    "orderTotal": 129900
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/customer/purchase-intents/{intentId}authenticatedGet purchase intent

Returns the full state of a purchase intent including items, shipment groups, delivery address, contact information, and price breakdown.

Requires

authenticated

Path parameters

  • intentIdstring · uuidrequiredPurchase intent ID

Response · 200

  • idstring · uuidrequiredPurchase intent ID
  • statusstringrequiredCurrent statusOne of: draft · confirming · confirmed · expired
  • storeIdstring · uuidrequiredStore ID
  • currencystringrequiredCurrency code (ISO 4217)
  • expiresAtstring · date-timerequiredExpiration timestamp
  • fulfillmentMethodstringSelected fulfillment methodOne of: delivery · pickup · locker
  • deliveryAddressobjectDelivery address snapshot
  • pickupLocationobjectPickup location snapshot
  • lockerTerminalobjectSelected locker terminal snapshot (id, externalId, name, address, city, countryCode, carrierCode, carrierName)
  • contactobjectrequiredContact information
    • phonestringContact phone number
    • emailstringContact email address
    • recipientNamestringDelivery recipient name (courier-facing)
    • customerNotestringOptional customer note
  • itemsarray<object>requiredLine items
    • idstring · uuidrequiredItem ID
    • listingVariantIdstring · uuidrequiredListing variant ID
    • productVariantIdstring · uuidProduct variant ID (if linked to canonical catalog)
    • titlestringrequiredItem title at time of intent creation
    • imageUrlstringPrimary image URL
    • quantityintegerrequiredQuantity
    • unitPriceintegerrequiredUnit price in cents
    • lineSubtotalintegerrequiredLine subtotal (unitPrice * quantity) in cents
    • lineDiscountintegerrequiredLine discount in cents
    • lineTotalintegerrequiredLine total after discount in cents
  • shipmentGroupsarray<object>requiredShipment groups with available methods
    • idstring · uuidrequiredShipment group ID
    • locationIdstring · uuidrequiredOrigin location ID
    • locationNamestringOrigin location name
    • fulfillmentMethodstringrequiredFulfillment method for this groupOne of: delivery · pickup · locker
    • selectedMethodIdstring · uuidrequiredSelected shipping/locker method ID
    • selectedMethodNamestringrequiredSelected shipping/locker method name
    • carrierNamestringCarrier name
    • carrierCodestringCarrier registry code (locker groups)
    • deliveryCostintegerrequiredDelivery cost in cents
    • estimatedMinDaysintegerEstimated minimum delivery days
    • estimatedMaxDaysintegerEstimated maximum delivery days
    • isFreeDeliverybooleanrequiredWhether delivery is free
    • itemIdsarray<string>requiredIntent item IDs in this group
    • availableMethodsarray<object>requiredAvailable shipping methods
  • offeredChannelsarray<string>Channels the store offers for this checkout. Populated only on the GET read; mutation responses carry it empty (the frontend refetches).One of: delivery · pickup · locker
  • lockerOptionsarray<object>Locker methods offered for this checkout. Populated only on the GET read; mutation responses carry it empty.
  • couponobjectApplied coupon details (null when no coupon is applied). `discountAmount` is the realized items/whole-order discount in cents; `deliveryDiscountAmount` is the realized delivery-target discount in cents. `discountKind`/`discountValue` are…
    • codestringCoupon code
    • discountKindstringReserved — currently null
    • discountValueintegerReserved — currently null
    • discountAmountintegerRealized items/whole-order discount in cents
    • deliveryDiscountAmountintegerRealized delivery-target discount in cents
  • priceBreakdownobjectrequired
    • itemsSubtotalintegerrequiredSum of all line item subtotals in cents
    • totalDiscountintegerrequiredTotal items/whole-order discount amount in cents
    • totalDeliveryCostintegerrequiredTotal delivery cost in cents
    • deliveryDiscountintegerrequiredDelivery discount from a delivery-target coupon in cents
    • orderTotalintegerrequiredFinal order total in cents (itemsSubtotal - totalDiscount + totalDeliveryCost - deliveryDiscount)
  • createdAtstring · date-timerequiredCreated timestamp
  • updatedAtstring · date-timerequiredUpdated timestamp

Errors

401 · 403 · 404 · 422 · 503 — See the error reference

httpRequest
GET /rest/v1/customer/purchase-intents/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "status": "draft",
  "storeId": "01914d0e-6f70-7182-9394-0f1021324356",
  "currency": "EUR",
  "expiresAt": "2026-09-10T09:24:11Z",
  "fulfillmentMethod": "delivery",
  "deliveryAddress": {},
  "pickupLocation": {},
  "lockerTerminal": {},
  "contact": {
    "phone": "Phone",
    "email": "Email",
    "recipientName": "Recipient name",
    "customerNote": "Customer note"
  },
  "items": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "listingVariantId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "productVariantId": "01914d0e-92a3-74b5-86c7-324354657689",
      "title": "Title",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 129900,
      "lineSubtotal": 129900,
      "lineDiscount": 0,
      "lineTotal": 129900
    }
  ],
  "shipmentGroups": [
    {
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "locationId": "01914d0e-8192-73a4-b5b6-213243546578",
      "locationName": "Location name",
      "fulfillmentMethod": "delivery",
      "selectedMethodId": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "selectedMethodName": "Selected method name",
      "carrierName": "Carrier name",
      "carrierCode": "Carrier code",
      "deliveryCost": 0,
      "estimatedMinDays": 0,
      "estimatedMaxDays": 0,
      "isFreeDelivery": false,
      "itemIds": [
        "01914d0e-5e6f-7071-8283-9e0f10213245"
      ],
      "availableMethods": [
        {}
      ]
    }
  ],
  "offeredChannels": [
    "delivery"
  ],
  "lockerOptions": [
    {}
  ],
  "coupon": {
    "code": "Code",
    "discountKind": "Discount kind",
    "discountValue": 0,
    "discountAmount": 129900,
    "deliveryDiscountAmount": 129900
  },
  "priceBreakdown": {
    "itemsSubtotal": 129900,
    "totalDiscount": 129900,
    "totalDeliveryCost": 129900,
    "deliveryDiscount": 0,
    "orderTotal": 129900
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
PUT/rest/v1/customer/purchase-intents/{id}/delivery-addressauthenticatedSet delivery address

Sets the delivery address and triggers shipping calculation. Auto-selects the cheapest eligible method per shipment group.

Requires

authenticated

Path parameters

  • idstring · uuidrequiredPurchase intent ID

Request body · application/json

  • addressIdstring · uuidrequiredDelivery address ID from the customer address book

Response · 200

  • idstring · uuidrequiredPurchase intent ID
  • statusstringrequiredCurrent statusOne of: draft · confirming · confirmed · expired
  • storeIdstring · uuidrequiredStore ID
  • currencystringrequiredCurrency code (ISO 4217)
  • expiresAtstring · date-timerequiredExpiration timestamp
  • fulfillmentMethodstringSelected fulfillment methodOne of: delivery · pickup · locker
  • deliveryAddressobjectDelivery address snapshot
  • pickupLocationobjectPickup location snapshot
  • lockerTerminalobjectSelected locker terminal snapshot (id, externalId, name, address, city, countryCode, carrierCode, carrierName)
  • contactobjectrequiredContact information
    • phonestringContact phone number
    • emailstringContact email address
    • recipientNamestringDelivery recipient name (courier-facing)
    • customerNotestringOptional customer note
  • itemsarray<object>requiredLine items
    • idstring · uuidrequiredItem ID
    • listingVariantIdstring · uuidrequiredListing variant ID
    • productVariantIdstring · uuidProduct variant ID (if linked to canonical catalog)
    • titlestringrequiredItem title at time of intent creation
    • imageUrlstringPrimary image URL
    • quantityintegerrequiredQuantity
    • unitPriceintegerrequiredUnit price in cents
    • lineSubtotalintegerrequiredLine subtotal (unitPrice * quantity) in cents
    • lineDiscountintegerrequiredLine discount in cents
    • lineTotalintegerrequiredLine total after discount in cents
  • shipmentGroupsarray<object>requiredShipment groups with available methods
    • idstring · uuidrequiredShipment group ID
    • locationIdstring · uuidrequiredOrigin location ID
    • locationNamestringOrigin location name
    • fulfillmentMethodstringrequiredFulfillment method for this groupOne of: delivery · pickup · locker
    • selectedMethodIdstring · uuidrequiredSelected shipping/locker method ID
    • selectedMethodNamestringrequiredSelected shipping/locker method name
    • carrierNamestringCarrier name
    • carrierCodestringCarrier registry code (locker groups)
    • deliveryCostintegerrequiredDelivery cost in cents
    • estimatedMinDaysintegerEstimated minimum delivery days
    • estimatedMaxDaysintegerEstimated maximum delivery days
    • isFreeDeliverybooleanrequiredWhether delivery is free
    • itemIdsarray<string>requiredIntent item IDs in this group
    • availableMethodsarray<object>requiredAvailable shipping methods
  • offeredChannelsarray<string>Channels the store offers for this checkout. Populated only on the GET read; mutation responses carry it empty (the frontend refetches).One of: delivery · pickup · locker
  • lockerOptionsarray<object>Locker methods offered for this checkout. Populated only on the GET read; mutation responses carry it empty.
  • couponobjectApplied coupon details (null when no coupon is applied). `discountAmount` is the realized items/whole-order discount in cents; `deliveryDiscountAmount` is the realized delivery-target discount in cents. `discountKind`/`discountValue` are…
    • codestringCoupon code
    • discountKindstringReserved — currently null
    • discountValueintegerReserved — currently null
    • discountAmountintegerRealized items/whole-order discount in cents
    • deliveryDiscountAmountintegerRealized delivery-target discount in cents
  • priceBreakdownobjectrequired
    • itemsSubtotalintegerrequiredSum of all line item subtotals in cents
    • totalDiscountintegerrequiredTotal items/whole-order discount amount in cents
    • totalDeliveryCostintegerrequiredTotal delivery cost in cents
    • deliveryDiscountintegerrequiredDelivery discount from a delivery-target coupon in cents
    • orderTotalintegerrequiredFinal order total in cents (itemsSubtotal - totalDiscount + totalDeliveryCost - deliveryDiscount)
  • createdAtstring · date-timerequiredCreated timestamp
  • updatedAtstring · date-timerequiredUpdated timestamp

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/customer/purchase-intents/01914d0e-5e6f-7071-8283-9e0f10213245/delivery-address
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "addressId": "01914d0e-92a3-74b5-86c7-324354657689"
}
jsonResponse · 200
{
  "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "status": "draft",
  "storeId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "currency": "EUR",
  "expiresAt": "2026-09-10T09:24:11Z",
  "fulfillmentMethod": "delivery",
  "deliveryAddress": {},
  "pickupLocation": {},
  "lockerTerminal": {},
  "contact": {
    "phone": "Phone",
    "email": "Email",
    "recipientName": "Recipient name",
    "customerNote": "Customer note"
  },
  "items": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "listingVariantId": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "productVariantId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "title": "Title",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 129900,
      "lineSubtotal": 129900,
      "lineDiscount": 0,
      "lineTotal": 129900
    }
  ],
  "shipmentGroups": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "locationId": "01914d0e-92a3-74b5-86c7-324354657689",
      "locationName": "Location name",
      "fulfillmentMethod": "delivery",
      "selectedMethodId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "selectedMethodName": "Selected method name",
      "carrierName": "Carrier name",
      "carrierCode": "Carrier code",
      "deliveryCost": 0,
      "estimatedMinDays": 0,
      "estimatedMaxDays": 0,
      "isFreeDelivery": false,
      "itemIds": [
        "01914d0e-a3b4-75c6-97d8-43546576879a"
      ],
      "availableMethods": [
        {}
      ]
    }
  ],
  "offeredChannels": [
    "delivery"
  ],
  "lockerOptions": [
    {}
  ],
  "coupon": {
    "code": "Code",
    "discountKind": "Discount kind",
    "discountValue": 0,
    "discountAmount": 129900,
    "deliveryDiscountAmount": 129900
  },
  "priceBreakdown": {
    "itemsSubtotal": 129900,
    "totalDiscount": 129900,
    "totalDeliveryCost": 129900,
    "deliveryDiscount": 0,
    "orderTotal": 129900
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PUT/rest/v1/customer/purchase-intents/{id}/contactauthenticatedSet contact information

Sets contact information (phone, email, optional note) on the purchase intent.

Requires

authenticated

Path parameters

  • idstring · uuidrequiredPurchase intent ID

Request body · application/json

  • phonestringrequiredContact phone number
  • emailstring · emailrequiredContact email address
  • recipientNamestringDelivery recipient name (courier-facing), an order-level contact attribute. Full-replace: omitting the field clears any previously set value. This differs from customerNote, which is only overwritten when present.
  • customerNotestringOptional customer note (max 500 characters)

Response · 200

  • idstring · uuidrequiredPurchase intent ID
  • statusstringrequiredCurrent statusOne of: draft · confirming · confirmed · expired
  • storeIdstring · uuidrequiredStore ID
  • currencystringrequiredCurrency code (ISO 4217)
  • expiresAtstring · date-timerequiredExpiration timestamp
  • fulfillmentMethodstringSelected fulfillment methodOne of: delivery · pickup · locker
  • deliveryAddressobjectDelivery address snapshot
  • pickupLocationobjectPickup location snapshot
  • lockerTerminalobjectSelected locker terminal snapshot (id, externalId, name, address, city, countryCode, carrierCode, carrierName)
  • contactobjectrequiredContact information
    • phonestringContact phone number
    • emailstringContact email address
    • recipientNamestringDelivery recipient name (courier-facing)
    • customerNotestringOptional customer note
  • itemsarray<object>requiredLine items
    • idstring · uuidrequiredItem ID
    • listingVariantIdstring · uuidrequiredListing variant ID
    • productVariantIdstring · uuidProduct variant ID (if linked to canonical catalog)
    • titlestringrequiredItem title at time of intent creation
    • imageUrlstringPrimary image URL
    • quantityintegerrequiredQuantity
    • unitPriceintegerrequiredUnit price in cents
    • lineSubtotalintegerrequiredLine subtotal (unitPrice * quantity) in cents
    • lineDiscountintegerrequiredLine discount in cents
    • lineTotalintegerrequiredLine total after discount in cents
  • shipmentGroupsarray<object>requiredShipment groups with available methods
    • idstring · uuidrequiredShipment group ID
    • locationIdstring · uuidrequiredOrigin location ID
    • locationNamestringOrigin location name
    • fulfillmentMethodstringrequiredFulfillment method for this groupOne of: delivery · pickup · locker
    • selectedMethodIdstring · uuidrequiredSelected shipping/locker method ID
    • selectedMethodNamestringrequiredSelected shipping/locker method name
    • carrierNamestringCarrier name
    • carrierCodestringCarrier registry code (locker groups)
    • deliveryCostintegerrequiredDelivery cost in cents
    • estimatedMinDaysintegerEstimated minimum delivery days
    • estimatedMaxDaysintegerEstimated maximum delivery days
    • isFreeDeliverybooleanrequiredWhether delivery is free
    • itemIdsarray<string>requiredIntent item IDs in this group
    • availableMethodsarray<object>requiredAvailable shipping methods
  • offeredChannelsarray<string>Channels the store offers for this checkout. Populated only on the GET read; mutation responses carry it empty (the frontend refetches).One of: delivery · pickup · locker
  • lockerOptionsarray<object>Locker methods offered for this checkout. Populated only on the GET read; mutation responses carry it empty.
  • couponobjectApplied coupon details (null when no coupon is applied). `discountAmount` is the realized items/whole-order discount in cents; `deliveryDiscountAmount` is the realized delivery-target discount in cents. `discountKind`/`discountValue` are…
    • codestringCoupon code
    • discountKindstringReserved — currently null
    • discountValueintegerReserved — currently null
    • discountAmountintegerRealized items/whole-order discount in cents
    • deliveryDiscountAmountintegerRealized delivery-target discount in cents
  • priceBreakdownobjectrequired
    • itemsSubtotalintegerrequiredSum of all line item subtotals in cents
    • totalDiscountintegerrequiredTotal items/whole-order discount amount in cents
    • totalDeliveryCostintegerrequiredTotal delivery cost in cents
    • deliveryDiscountintegerrequiredDelivery discount from a delivery-target coupon in cents
    • orderTotalintegerrequiredFinal order total in cents (itemsSubtotal - totalDiscount + totalDeliveryCost - deliveryDiscount)
  • createdAtstring · date-timerequiredCreated timestamp
  • updatedAtstring · date-timerequiredUpdated timestamp

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/customer/purchase-intents/01914d0e-c5d6-77e8-b9fa-6576879aabbc/contact
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "phone": "+37061234567",
  "email": "seller@example.com",
  "recipientName": "Jonas Jonaitis",
  "customerNote": "Customer note"
}
jsonResponse · 200
{
  "id": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "status": "draft",
  "storeId": "01914d0e-6f70-7182-9394-0f1021324356",
  "currency": "EUR",
  "expiresAt": "2026-09-10T09:24:11Z",
  "fulfillmentMethod": "delivery",
  "deliveryAddress": {},
  "pickupLocation": {},
  "lockerTerminal": {},
  "contact": {
    "phone": "Phone",
    "email": "Email",
    "recipientName": "Recipient name",
    "customerNote": "Customer note"
  },
  "items": [
    {
      "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "listingVariantId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "productVariantId": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "title": "Title",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 129900,
      "lineSubtotal": 129900,
      "lineDiscount": 0,
      "lineTotal": 129900
    }
  ],
  "shipmentGroups": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "locationId": "01914d0e-8192-73a4-b5b6-213243546578",
      "locationName": "Location name",
      "fulfillmentMethod": "delivery",
      "selectedMethodId": "01914d0e-5e6f-7071-8283-9e0f10213245",
      "selectedMethodName": "Selected method name",
      "carrierName": "Carrier name",
      "carrierCode": "Carrier code",
      "deliveryCost": 0,
      "estimatedMinDays": 0,
      "estimatedMaxDays": 0,
      "isFreeDelivery": false,
      "itemIds": [
        "01914d0e-92a3-74b5-86c7-324354657689"
      ],
      "availableMethods": [
        {}
      ]
    }
  ],
  "offeredChannels": [
    "delivery"
  ],
  "lockerOptions": [
    {}
  ],
  "coupon": {
    "code": "Code",
    "discountKind": "Discount kind",
    "discountValue": 0,
    "discountAmount": 129900,
    "deliveryDiscountAmount": 129900
  },
  "priceBreakdown": {
    "itemsSubtotal": 129900,
    "totalDiscount": 129900,
    "totalDeliveryCost": 129900,
    "deliveryDiscount": 0,
    "orderTotal": 129900
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PUT/rest/v1/customer/purchase-intents/{intentId}/fulfillment-optionauthenticatedSelect fulfillment option

Selects the fulfillment option for the purchase intent. For delivery, selects a specific shipping method. For pickup, selects a pickup location.

Requires

authenticated

Path parameters

  • intentIdstring · uuidrequiredPurchase intent ID

Request body · application/json

  • shippingMethodIdstring · uuidShipping method ID (required for courier delivery)
  • locationIdstring · uuidLocation ID (required for pickup)
  • groupIdstring · uuidShipment group location ID (for delivery override of a specific group)
  • lockerMethodIdstring · uuidLocker method ID (required for parcel-locker delivery)
  • terminalIdstring · uuidChosen terminal ID (required with a locker method)

Response · 200

  • idstring · uuidrequiredPurchase intent ID
  • statusstringrequiredCurrent statusOne of: draft · confirming · confirmed · expired
  • storeIdstring · uuidrequiredStore ID
  • currencystringrequiredCurrency code (ISO 4217)
  • expiresAtstring · date-timerequiredExpiration timestamp
  • fulfillmentMethodstringSelected fulfillment methodOne of: delivery · pickup · locker
  • deliveryAddressobjectDelivery address snapshot
  • pickupLocationobjectPickup location snapshot
  • lockerTerminalobjectSelected locker terminal snapshot (id, externalId, name, address, city, countryCode, carrierCode, carrierName)
  • contactobjectrequiredContact information
    • phonestringContact phone number
    • emailstringContact email address
    • recipientNamestringDelivery recipient name (courier-facing)
    • customerNotestringOptional customer note
  • itemsarray<object>requiredLine items
    • idstring · uuidrequiredItem ID
    • listingVariantIdstring · uuidrequiredListing variant ID
    • productVariantIdstring · uuidProduct variant ID (if linked to canonical catalog)
    • titlestringrequiredItem title at time of intent creation
    • imageUrlstringPrimary image URL
    • quantityintegerrequiredQuantity
    • unitPriceintegerrequiredUnit price in cents
    • lineSubtotalintegerrequiredLine subtotal (unitPrice * quantity) in cents
    • lineDiscountintegerrequiredLine discount in cents
    • lineTotalintegerrequiredLine total after discount in cents
  • shipmentGroupsarray<object>requiredShipment groups with available methods
    • idstring · uuidrequiredShipment group ID
    • locationIdstring · uuidrequiredOrigin location ID
    • locationNamestringOrigin location name
    • fulfillmentMethodstringrequiredFulfillment method for this groupOne of: delivery · pickup · locker
    • selectedMethodIdstring · uuidrequiredSelected shipping/locker method ID
    • selectedMethodNamestringrequiredSelected shipping/locker method name
    • carrierNamestringCarrier name
    • carrierCodestringCarrier registry code (locker groups)
    • deliveryCostintegerrequiredDelivery cost in cents
    • estimatedMinDaysintegerEstimated minimum delivery days
    • estimatedMaxDaysintegerEstimated maximum delivery days
    • isFreeDeliverybooleanrequiredWhether delivery is free
    • itemIdsarray<string>requiredIntent item IDs in this group
    • availableMethodsarray<object>requiredAvailable shipping methods
  • offeredChannelsarray<string>Channels the store offers for this checkout. Populated only on the GET read; mutation responses carry it empty (the frontend refetches).One of: delivery · pickup · locker
  • lockerOptionsarray<object>Locker methods offered for this checkout. Populated only on the GET read; mutation responses carry it empty.
  • couponobjectApplied coupon details (null when no coupon is applied). `discountAmount` is the realized items/whole-order discount in cents; `deliveryDiscountAmount` is the realized delivery-target discount in cents. `discountKind`/`discountValue` are…
    • codestringCoupon code
    • discountKindstringReserved — currently null
    • discountValueintegerReserved — currently null
    • discountAmountintegerRealized items/whole-order discount in cents
    • deliveryDiscountAmountintegerRealized delivery-target discount in cents
  • priceBreakdownobjectrequired
    • itemsSubtotalintegerrequiredSum of all line item subtotals in cents
    • totalDiscountintegerrequiredTotal items/whole-order discount amount in cents
    • totalDeliveryCostintegerrequiredTotal delivery cost in cents
    • deliveryDiscountintegerrequiredDelivery discount from a delivery-target coupon in cents
    • orderTotalintegerrequiredFinal order total in cents (itemsSubtotal - totalDiscount + totalDeliveryCost - deliveryDiscount)
  • createdAtstring · date-timerequiredCreated timestamp
  • updatedAtstring · date-timerequiredUpdated timestamp

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/customer/purchase-intents/01914d0e-8192-73a4-b5b6-213243546578/fulfillment-option
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "shippingMethodId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "locationId": "01914d0e-7081-7293-a4a5-102132435467",
  "groupId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "lockerMethodId": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "terminalId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12"
}
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "status": "draft",
  "storeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "currency": "EUR",
  "expiresAt": "2026-09-10T09:24:11Z",
  "fulfillmentMethod": "delivery",
  "deliveryAddress": {},
  "pickupLocation": {},
  "lockerTerminal": {},
  "contact": {
    "phone": "Phone",
    "email": "Email",
    "recipientName": "Recipient name",
    "customerNote": "Customer note"
  },
  "items": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "listingVariantId": "01914d0e-8192-73a4-b5b6-213243546578",
      "productVariantId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "title": "Title",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 129900,
      "lineSubtotal": 129900,
      "lineDiscount": 0,
      "lineTotal": 129900
    }
  ],
  "shipmentGroups": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "locationId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "locationName": "Location name",
      "fulfillmentMethod": "delivery",
      "selectedMethodId": "01914d0e-7081-7293-a4a5-102132435467",
      "selectedMethodName": "Selected method name",
      "carrierName": "Carrier name",
      "carrierCode": "Carrier code",
      "deliveryCost": 0,
      "estimatedMinDays": 0,
      "estimatedMaxDays": 0,
      "isFreeDelivery": false,
      "itemIds": [
        "01914d0e-7081-7293-a4a5-102132435467"
      ],
      "availableMethods": [
        {}
      ]
    }
  ],
  "offeredChannels": [
    "delivery"
  ],
  "lockerOptions": [
    {}
  ],
  "coupon": {
    "code": "Code",
    "discountKind": "Discount kind",
    "discountValue": 0,
    "discountAmount": 129900,
    "deliveryDiscountAmount": 129900
  },
  "priceBreakdown": {
    "itemsSubtotal": 129900,
    "totalDiscount": 129900,
    "totalDeliveryCost": 129900,
    "deliveryDiscount": 0,
    "orderTotal": 129900
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/customer/purchase-intents/{id}/couponauthenticatedApply coupon

Applies a coupon code to the purchase intent. The intent is re-quoted against svc-showroom and the realized discount is written to the price breakdown (`totalDiscount` for items/whole-order coupons, `deliveryDiscount` for a delivery-target…

Requires

authenticated

Path parameters

  • idstring · uuidrequiredPurchase intent ID

Request body · application/json

  • couponCodestringrequiredCoupon code

Response · 200

  • idstring · uuidrequiredPurchase intent ID
  • statusstringrequiredCurrent statusOne of: draft · confirming · confirmed · expired
  • storeIdstring · uuidrequiredStore ID
  • currencystringrequiredCurrency code (ISO 4217)
  • expiresAtstring · date-timerequiredExpiration timestamp
  • fulfillmentMethodstringSelected fulfillment methodOne of: delivery · pickup · locker
  • deliveryAddressobjectDelivery address snapshot
  • pickupLocationobjectPickup location snapshot
  • lockerTerminalobjectSelected locker terminal snapshot (id, externalId, name, address, city, countryCode, carrierCode, carrierName)
  • contactobjectrequiredContact information
    • phonestringContact phone number
    • emailstringContact email address
    • recipientNamestringDelivery recipient name (courier-facing)
    • customerNotestringOptional customer note
  • itemsarray<object>requiredLine items
    • idstring · uuidrequiredItem ID
    • listingVariantIdstring · uuidrequiredListing variant ID
    • productVariantIdstring · uuidProduct variant ID (if linked to canonical catalog)
    • titlestringrequiredItem title at time of intent creation
    • imageUrlstringPrimary image URL
    • quantityintegerrequiredQuantity
    • unitPriceintegerrequiredUnit price in cents
    • lineSubtotalintegerrequiredLine subtotal (unitPrice * quantity) in cents
    • lineDiscountintegerrequiredLine discount in cents
    • lineTotalintegerrequiredLine total after discount in cents
  • shipmentGroupsarray<object>requiredShipment groups with available methods
    • idstring · uuidrequiredShipment group ID
    • locationIdstring · uuidrequiredOrigin location ID
    • locationNamestringOrigin location name
    • fulfillmentMethodstringrequiredFulfillment method for this groupOne of: delivery · pickup · locker
    • selectedMethodIdstring · uuidrequiredSelected shipping/locker method ID
    • selectedMethodNamestringrequiredSelected shipping/locker method name
    • carrierNamestringCarrier name
    • carrierCodestringCarrier registry code (locker groups)
    • deliveryCostintegerrequiredDelivery cost in cents
    • estimatedMinDaysintegerEstimated minimum delivery days
    • estimatedMaxDaysintegerEstimated maximum delivery days
    • isFreeDeliverybooleanrequiredWhether delivery is free
    • itemIdsarray<string>requiredIntent item IDs in this group
    • availableMethodsarray<object>requiredAvailable shipping methods
  • offeredChannelsarray<string>Channels the store offers for this checkout. Populated only on the GET read; mutation responses carry it empty (the frontend refetches).One of: delivery · pickup · locker
  • lockerOptionsarray<object>Locker methods offered for this checkout. Populated only on the GET read; mutation responses carry it empty.
  • couponobjectApplied coupon details (null when no coupon is applied). `discountAmount` is the realized items/whole-order discount in cents; `deliveryDiscountAmount` is the realized delivery-target discount in cents. `discountKind`/`discountValue` are…
    • codestringCoupon code
    • discountKindstringReserved — currently null
    • discountValueintegerReserved — currently null
    • discountAmountintegerRealized items/whole-order discount in cents
    • deliveryDiscountAmountintegerRealized delivery-target discount in cents
  • priceBreakdownobjectrequired
    • itemsSubtotalintegerrequiredSum of all line item subtotals in cents
    • totalDiscountintegerrequiredTotal items/whole-order discount amount in cents
    • totalDeliveryCostintegerrequiredTotal delivery cost in cents
    • deliveryDiscountintegerrequiredDelivery discount from a delivery-target coupon in cents
    • orderTotalintegerrequiredFinal order total in cents (itemsSubtotal - totalDiscount + totalDeliveryCost - deliveryDiscount)
  • createdAtstring · date-timerequiredCreated timestamp
  • updatedAtstring · date-timerequiredUpdated timestamp

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/customer/purchase-intents/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/coupon
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "couponCode": "WELCOME10"
}
jsonResponse · 200
{
  "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "status": "draft",
  "storeId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "currency": "EUR",
  "expiresAt": "2026-09-10T09:24:11Z",
  "fulfillmentMethod": "delivery",
  "deliveryAddress": {},
  "pickupLocation": {},
  "lockerTerminal": {},
  "contact": {
    "phone": "Phone",
    "email": "Email",
    "recipientName": "Recipient name",
    "customerNote": "Customer note"
  },
  "items": [
    {
      "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "listingVariantId": "01914d0e-7081-7293-a4a5-102132435467",
      "productVariantId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "title": "Title",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 129900,
      "lineSubtotal": 129900,
      "lineDiscount": 0,
      "lineTotal": 129900
    }
  ],
  "shipmentGroups": [
    {
      "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "locationId": "01914d0e-7081-7293-a4a5-102132435467",
      "locationName": "Location name",
      "fulfillmentMethod": "delivery",
      "selectedMethodId": "01914d0e-6f70-7182-9394-0f1021324356",
      "selectedMethodName": "Selected method name",
      "carrierName": "Carrier name",
      "carrierCode": "Carrier code",
      "deliveryCost": 0,
      "estimatedMinDays": 0,
      "estimatedMaxDays": 0,
      "isFreeDelivery": false,
      "itemIds": [
        "01914d0e-4d5e-7f60-b172-8d9e0f102134"
      ],
      "availableMethods": [
        {}
      ]
    }
  ],
  "offeredChannels": [
    "delivery"
  ],
  "lockerOptions": [
    {}
  ],
  "coupon": {
    "code": "Code",
    "discountKind": "Discount kind",
    "discountValue": 0,
    "discountAmount": 129900,
    "deliveryDiscountAmount": 129900
  },
  "priceBreakdown": {
    "itemsSubtotal": 129900,
    "totalDiscount": 129900,
    "totalDeliveryCost": 129900,
    "deliveryDiscount": 0,
    "orderTotal": 129900
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
DELETE/rest/v1/customer/purchase-intents/{id}/couponauthenticatedRemove coupon

Removes the applied coupon from the purchase intent.

Requires

authenticated

Path parameters

  • idstring · uuidrequiredPurchase intent ID

Response · 200

  • idstring · uuidrequiredPurchase intent ID
  • statusstringrequiredCurrent statusOne of: draft · confirming · confirmed · expired
  • storeIdstring · uuidrequiredStore ID
  • currencystringrequiredCurrency code (ISO 4217)
  • expiresAtstring · date-timerequiredExpiration timestamp
  • fulfillmentMethodstringSelected fulfillment methodOne of: delivery · pickup · locker
  • deliveryAddressobjectDelivery address snapshot
  • pickupLocationobjectPickup location snapshot
  • lockerTerminalobjectSelected locker terminal snapshot (id, externalId, name, address, city, countryCode, carrierCode, carrierName)
  • contactobjectrequiredContact information
    • phonestringContact phone number
    • emailstringContact email address
    • recipientNamestringDelivery recipient name (courier-facing)
    • customerNotestringOptional customer note
  • itemsarray<object>requiredLine items
    • idstring · uuidrequiredItem ID
    • listingVariantIdstring · uuidrequiredListing variant ID
    • productVariantIdstring · uuidProduct variant ID (if linked to canonical catalog)
    • titlestringrequiredItem title at time of intent creation
    • imageUrlstringPrimary image URL
    • quantityintegerrequiredQuantity
    • unitPriceintegerrequiredUnit price in cents
    • lineSubtotalintegerrequiredLine subtotal (unitPrice * quantity) in cents
    • lineDiscountintegerrequiredLine discount in cents
    • lineTotalintegerrequiredLine total after discount in cents
  • shipmentGroupsarray<object>requiredShipment groups with available methods
    • idstring · uuidrequiredShipment group ID
    • locationIdstring · uuidrequiredOrigin location ID
    • locationNamestringOrigin location name
    • fulfillmentMethodstringrequiredFulfillment method for this groupOne of: delivery · pickup · locker
    • selectedMethodIdstring · uuidrequiredSelected shipping/locker method ID
    • selectedMethodNamestringrequiredSelected shipping/locker method name
    • carrierNamestringCarrier name
    • carrierCodestringCarrier registry code (locker groups)
    • deliveryCostintegerrequiredDelivery cost in cents
    • estimatedMinDaysintegerEstimated minimum delivery days
    • estimatedMaxDaysintegerEstimated maximum delivery days
    • isFreeDeliverybooleanrequiredWhether delivery is free
    • itemIdsarray<string>requiredIntent item IDs in this group
    • availableMethodsarray<object>requiredAvailable shipping methods
  • offeredChannelsarray<string>Channels the store offers for this checkout. Populated only on the GET read; mutation responses carry it empty (the frontend refetches).One of: delivery · pickup · locker
  • lockerOptionsarray<object>Locker methods offered for this checkout. Populated only on the GET read; mutation responses carry it empty.
  • couponobjectApplied coupon details (null when no coupon is applied). `discountAmount` is the realized items/whole-order discount in cents; `deliveryDiscountAmount` is the realized delivery-target discount in cents. `discountKind`/`discountValue` are…
    • codestringCoupon code
    • discountKindstringReserved — currently null
    • discountValueintegerReserved — currently null
    • discountAmountintegerRealized items/whole-order discount in cents
    • deliveryDiscountAmountintegerRealized delivery-target discount in cents
  • priceBreakdownobjectrequired
    • itemsSubtotalintegerrequiredSum of all line item subtotals in cents
    • totalDiscountintegerrequiredTotal items/whole-order discount amount in cents
    • totalDeliveryCostintegerrequiredTotal delivery cost in cents
    • deliveryDiscountintegerrequiredDelivery discount from a delivery-target coupon in cents
    • orderTotalintegerrequiredFinal order total in cents (itemsSubtotal - totalDiscount + totalDeliveryCost - deliveryDiscount)
  • createdAtstring · date-timerequiredCreated timestamp
  • updatedAtstring · date-timerequiredUpdated timestamp

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/customer/purchase-intents/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/coupon
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "status": "draft",
  "storeId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "currency": "EUR",
  "expiresAt": "2026-09-10T09:24:11Z",
  "fulfillmentMethod": "delivery",
  "deliveryAddress": {},
  "pickupLocation": {},
  "lockerTerminal": {},
  "contact": {
    "phone": "Phone",
    "email": "Email",
    "recipientName": "Recipient name",
    "customerNote": "Customer note"
  },
  "items": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "listingVariantId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "productVariantId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "title": "Title",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 129900,
      "lineSubtotal": 129900,
      "lineDiscount": 0,
      "lineTotal": 129900
    }
  ],
  "shipmentGroups": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "locationId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "locationName": "Location name",
      "fulfillmentMethod": "delivery",
      "selectedMethodId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "selectedMethodName": "Selected method name",
      "carrierName": "Carrier name",
      "carrierCode": "Carrier code",
      "deliveryCost": 0,
      "estimatedMinDays": 0,
      "estimatedMaxDays": 0,
      "isFreeDelivery": false,
      "itemIds": [
        "01914d0e-7081-7293-a4a5-102132435467"
      ],
      "availableMethods": [
        {}
      ]
    }
  ],
  "offeredChannels": [
    "delivery"
  ],
  "lockerOptions": [
    {}
  ],
  "coupon": {
    "code": "Code",
    "discountKind": "Discount kind",
    "discountValue": 0,
    "discountAmount": 129900,
    "deliveryDiscountAmount": 129900
  },
  "priceBreakdown": {
    "itemsSubtotal": 129900,
    "totalDiscount": 129900,
    "totalDeliveryCost": 129900,
    "deliveryDiscount": 0,
    "orderTotal": 129900
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/customer/purchase-intents/{id}/confirmauthenticatedConfirm purchase intent

Confirms the purchase intent: validates completeness, re-checks shipping costs, creates the Order, commits stock, and initiates payment. Returns order ID and payment redirect URL. The order is created in `new` status with a 1-hour TTL; if…

Requires

authenticated

Path parameters

  • idstring · uuidrequiredPurchase intent ID

Request body · application/json

  • paymentMethodKeystringrequiredPayment method key
  • paymentFlowstringProvider-specific payment flow type
  • paymentCountryCodestringISO 3166-1 alpha-2 country code for payment
  • platformstringClient platform initiating checkoutOne of: web · mobile

Response · 201

  • orderIdstring · uuidrequiredOrder ID
  • orderReferencestringrequiredHuman-readable order reference
  • paymentRedirectUrlstring · urirequiredPayment redirect URL
  • totalAmountintegerrequiredTotal amount in cents
  • currencystringrequiredCurrency (ISO 4217)

Errors

400 · 401 · 403 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/customer/purchase-intents/01914d0e-c5d6-77e8-b9fa-6576879aabbc/confirm
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "paymentMethodKey": "swedbank",
  "paymentFlow": "Payment flow",
  "paymentCountryCode": "LT",
  "platform": "web"
}
jsonResponse · 201
{
  "orderId": "01914d0e-6f70-7182-9394-0f1021324356",
  "orderReference": "PM-2026-A1B2C3",
  "paymentRedirectUrl": "https://api.example.com",
  "totalAmount": 3500,
  "currency": "EUR"
}
write#

Customer Orders 3 operations

GET/rest/v1/customer/ordersauthenticatedList customer orders

Returns the authenticated customer's orders with cursor-based pagination. Supports filtering by semantic status: active (non-terminal orders including new, paid, in_progress, delivered), completed, or cancelled.

Requires

authenticated

Query parameters

  • afterstring · uuidCursor for forward pagination (UUID)
  • beforestring · uuidCursor for backward pagination (UUID)
  • limitintegerPage size (1-100, default 20)
  • includeTotalCountbooleanInclude the total item count in `_metadata`
  • statusstringSemantic status filter. `all` returns every status. `active` includes new, paid, in_progress, and delivered orders. `completed` and `cancelled` filter to their respective terminal states.One of: all · active · completed · cancelled

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequiredOrder ID
    • orderReferencestringrequiredHuman-readable order reference
    • statusstringrequiredOrder status machine valueOne of: new · paid · in_progress · delivered · completed · cancelled
    • displayStatusstringrequiredHuman-readable status label for customer
    • totalAmountintegerrequiredThe amount charged for the order, in cents (items and delivery, after any coupon)
    • currencystringrequiredISO 4217 currency code
    • itemCountintegerrequiredNumber of distinct line items
    • unreadMessageCountintegerrequiredNumber of unread messages (reserved, currently 0)
    • createdAtstring · date-timerequired
  • _metadataobjectrequiredCursor-based pagination metadata
    • limitintegerrequiredRequested page size (echoed back)
    • hasMorebooleanrequiredWhether more items exist beyond this page
    • nextCursorstring · uuidUUID to pass as `?after=` for the next page
    • prevCursorstring · uuidUUID to pass as `?before=` for the previous page
    • totalCountintegerTotal item count (only when `includeTotalCount=true`)

Errors

401 · 403 · 422 · 503 — See the error reference

httpRequest
GET /rest/v1/customer/orders
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "orderReference": "MKT-2026-A3F9K2",
      "status": "new",
      "displayStatus": "Awaiting payment",
      "totalAmount": 4998,
      "currency": "EUR",
      "itemCount": 0,
      "unreadMessageCount": 0,
      "createdAt": "2026-09-10T09:24:11Z"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "prevCursor": "01914d0e-b4c5-76d7-a8e9-546576879aab",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/customer/orders/{orderId}authenticatedGet customer order detail

Returns the full detail of a customer's order including items, shipments, price breakdown, payment summary, delivery address and cancellation info. The curated activity timeline is a seller-only read — there is no customer timeline…

Requires

authenticated

Path parameters

  • orderIdstring · uuidrequiredOrder ID

Response · 200

  • idstring · uuidrequiredOrder ID
  • orderReferencestringrequiredHuman-readable order reference
  • storeIdstring · uuidrequiredOwning store ID for the order
  • statusstringrequiredOne of: new · paid · in_progress · delivered · completed · cancelled
  • displayStatusstringrequiredCustomer-facing status label
  • itemsarray<object>required
    • idstringrequiredOrder item ID
    • chosenItemLabelstringrequiredProduct title with variant description (e.g., 'Running Shoes, Size 42 / Black')
    • imageUrlstringPrimary product image URL
    • quantityintegerrequiredOrdered quantity
    • unitPriceintegerrequiredUnit price in cents
    • lineTotalintegerrequiredLine total in cents (unitPrice x quantity)
    • currencystringrequiredISO 4217 currency code
    • shipmentIdstringID of the shipment this item belongs to
  • shipmentsarray<object>required
    • idstring · uuidrequiredShipment ID
    • sequenceNumberintegerrequiredShipment sequence (1-based)
    • totalShipmentsintegerrequiredTotal number of shipments in the order
    • statusstringrequiredShipment status machine valueOne of: pending · processed · shipped · delivered
    • displayStatusstringrequiredHuman-readable shipment status (varies by fulfillment method)
    • fulfillmentMethodstringrequiredOne of: delivery · pickup · locker
    • methodNamestringShipping method name. On a pickup shipment it holds the pickup location's name, so show it as a place, not as a shipping method.
    • carrierCodestringRegistry carrier code (set when a carrier is resolved)
    • carrierNamestringCarrier name
    • deliveryCostintegerrequiredDelivery cost in cents for this shipment
    • currencystringrequired
    • estimatedDeliveryDatestring · dateEstimated delivery date (YYYY-MM-DD)
    • trackingNumberstringTracking number (set when shipment advances to Shipped)
    • trackingUrlstringCarrier tracking URL, resolved at read time from the carrier registry template. Null when the carrier, template, or tracking number is missing.
  • priceBreakdownobjectrequiredWhat the customer paid, per component. There is no discount line: each component is already net of its coupon, so `orderTotal` is always `itemsSubtotal + totalDeliveryCost` and equals the amount charged.
    • itemsSubtotalintegerrequiredSum of all item line totals in cents — after an items or whole-order coupon.
    • totalDeliveryCostintegerrequiredSum of all shipment delivery costs in cents, after a delivery coupon. Each shipment's own `deliveryCost` stays the fee before the coupon.
    • orderTotalintegerrequiredThe amount charged, in cents (itemsSubtotal + totalDeliveryCost).
    • currencystringrequiredISO 4217 currency code
  • paymentobjectPayment summary. Null when the order has no payment rows yet.
    • statusstringrequiredCanonical effective-payment status. `awaiting_settlement` means the buyer's money has left their bank and has not arrived yet: the order is held open with no deadline, and neither a retry nor a cancellation is offered while it lasts. Never…One of: pending · awaiting_settlement · paid · failed · expired
    • statusAtstring · date-timerequiredTimestamp when the payment reached its current status (terminal-safe)
  • cancellationobjectCancellation details (null when order is not cancelled)
    • actorstringWho cancelled the order. Populated for every cancellation the platform records; null only for orders cancelled before the actor was persisted.One of: customer · seller · system
    • reasonstringThe seller's own words, verbatim including line breaks. Present only when `actor` is `seller`; null for `customer` and `system` cancellations (a system cancellation's internal note is not exposed).
    • cancelledAtstring · date-timerequired
  • customerNotestringNote left by the customer at checkout
  • deliveryAddressobjectTyped shipping-address snapshot recorded at order creation, discriminated on `type`. Null only when the order carries no snapshot. One of 3 variants.
    • typestringrequiredSnapshot discriminator
    • recipientNamestringDelivery recipient captured with the order (order-level contact, not the address book)
    • streetAddressstringStreet address line
    • apartmentstringApartment / flat / unit number, snapshotted from the delivery address
    • citystring
    • postalCodestring
    • countryCodestringISO 3166-1 alpha-2 country code
    • courierNotestringFree-text courier note, snapshotted from the delivery address
    • mapPinLatnumber · floatDelivery map pin latitude, snapshotted from the delivery address
    • mapPinLngnumber · floatDelivery map pin longitude, snapshotted from the delivery address
    • contactPhonestringCourier-facing contact phone captured with the order (order-level contact)
    • contactEmailstringContact email captured with the order
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 503 — See the error reference

httpRequest
GET /rest/v1/customer/orders/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "orderReference": "MKT-2026-A3F9K2",
  "storeId": "01914d0e-6f70-7182-9394-0f1021324356",
  "status": "new",
  "displayStatus": "In progress",
  "items": [
    {
      "id": "Id",
      "chosenItemLabel": "Chosen item label",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 2499,
      "lineTotal": 4998,
      "currency": "EUR",
      "shipmentId": "Shipment id"
    }
  ],
  "shipments": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "sequenceNumber": 1,
      "totalShipments": 2,
      "status": "pending",
      "displayStatus": "Shipped",
      "fulfillmentMethod": "delivery",
      "methodName": "Method name",
      "carrierCode": "Carrier code",
      "carrierName": "Carrier name",
      "deliveryCost": 499,
      "currency": "EUR",
      "estimatedDeliveryDate": "2026-09-10",
      "trackingNumber": "LP123456789LT",
      "trackingUrl": "Tracking url"
    }
  ],
  "priceBreakdown": {
    "itemsSubtotal": 4998,
    "totalDeliveryCost": 499,
    "orderTotal": 5497,
    "currency": "EUR"
  },
  "payment": {
    "status": "pending",
    "statusAt": "2026-09-10T09:24:11Z"
  },
  "cancellation": {
    "actor": "customer",
    "reason": "Reason",
    "cancelledAt": "2026-09-10T09:24:11Z"
  },
  "customerNote": "Customer note",
  "deliveryAddress": {
    "type": "Type",
    "recipientName": "Recipient name",
    "streetAddress": "Street address",
    "apartment": "Apartment",
    "city": "City",
    "postalCode": "Postal code",
    "countryCode": "Country code",
    "courierNote": "Courier note",
    "mapPinLat": 0,
    "mapPinLng": 0,
    "contactPhone": "Contact phone",
    "contactEmail": "Contact email"
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
POST/rest/v1/customer/orders/{orderId}/cancelauthenticatedCancel order as customer

Cancels an order as a customer. Only allowed when the order is in New status (before payment). No request body required. Refused with 422 while a payment attempt on the order is still being settled: the buyer's transfer has left their bank…

Requires

authenticated

Path parameters

  • orderIdstring · uuidrequiredOrder ID

Response · 200

  • orderIdstring · uuidrequired
  • orderReferencestringrequired
  • statusstringrequired
  • displayStatusstringrequired
  • previousStatusstringrequiredOrder status before cancellation
  • cancellationobjectrequired
    • actorstringrequiredOne of: customer · seller · system
    • reasonstringPresent only when `actor` is `seller`; a customer cancellation echoes null.
    • cancelledAtstring · date-timerequired
  • stockReleasedbooleanrequiredWhether committed stock was released back to inventory

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/customer/orders/01914d0e-8192-73a4-b5b6-213243546578/cancel
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "orderId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "orderReference": "MKT-2026-ABCD",
  "status": "cancelled",
  "displayStatus": "Cancelled",
  "previousStatus": "paid",
  "cancellation": {
    "actor": "customer",
    "reason": "Items damaged in warehouse",
    "cancelledAt": "2026-09-10T09:24:11Z"
  },
  "stockReleased": false
}
write#

Seller Orders 6 operations

GET/rest/v1/purchase/stores/{storeId}/ordersorders:readList seller orders

Returns the seller's orders for a specific store with cursor-based pagination. Scoped to the store in the path. Supports filtering by individual order statuses (comma-separated), a free-text search, a created-at date range, and sorting by…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID

Query parameters

  • statusstringComma-separated individual order statuses (e.g. `new,paid,in_progress`). Unknown values are ignored.
  • searchstringSearch by order reference or buyer name (case-insensitive substring)
  • dateFromstring · dateFilter orders created on or after this date (ISO 8601)
  • dateTostring · dateFilter orders created on or before this date (ISO 8601)
  • sortBystringSort fieldOne of: createdAt · totalAmount
  • sortDirstringSort directionOne of: asc · desc
  • afterstring · uuidCursor for forward pagination (UUID)
  • beforestring · uuidCursor for backward pagination (UUID)
  • limitintegerPage size (1-100, default 20)
  • includeTotalCountbooleanInclude the total item count in `_metadata`

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequiredOrder ID
    • orderReferencestringrequiredHuman-readable order reference
    • statusstringrequiredOrder status machine valueOne of: new · paid · in_progress · delivered · completed · cancelled
    • displayStatusstringrequiredHuman-readable status label for the seller
    • customerNamestringBuyer recipient name from the shipping-address snapshot
    • customerEmailstringBuyer contact email from the shipping-address snapshot
    • buyerUserIdstringBuyer marketplace user id
    • fulfillmentMethodstringFulfillment method of the first shipment (null when the order has no shipments)One of: delivery · pickup · locker
    • totalAmountintegerrequiredThe amount charged for the order, in cents (items and delivery, after any coupon)
    • currencystringrequiredISO 4217 currency code
    • itemCountintegerrequiredNumber of distinct line items
    • unreadMessageCountintegerrequiredNumber of unread messages (reserved, currently 0)
    • slaBreachedbooleanrequiredTrue while the order is still Paid after the two-business-day processing SLA elapsed (J5.4); clears when the order advances or is cancelled.
    • createdAtstring · date-timerequired
  • _metadataobjectrequiredCursor-based pagination metadata
    • limitintegerrequiredRequested page size (echoed back)
    • hasMorebooleanrequiredWhether more items exist beyond this page
    • nextCursorstring · uuidUUID to pass as `?after=` for the next page
    • prevCursorstring · uuidUUID to pass as `?before=` for the previous page
    • totalCountintegerTotal item count (only when `includeTotalCount=true`)

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-7081-7293-a4a5-102132435467/orders
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
      "orderReference": "MKT-2026-A3F9K2",
      "status": "new",
      "displayStatus": "Payment received",
      "customerName": "Customer name",
      "customerEmail": "Customer email",
      "buyerUserId": "Buyer user id",
      "fulfillmentMethod": "delivery",
      "totalAmount": 4998,
      "currency": "EUR",
      "itemCount": 0,
      "unreadMessageCount": 0,
      "slaBreached": false,
      "createdAt": "2026-09-10T09:24:11Z"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-6f70-7182-9394-0f1021324356",
    "prevCursor": "01914d0e-a3b4-75c6-97d8-43546576879a",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/purchase/stores/{storeId}/orders/{orderId}orders:readGet seller order detail

Returns the full detail of a seller's order including customer identity, items with physical attributes, shipments, price breakdown, payment summary, and cancellation info. Store ownership is enforced: a missing order, or a store that is…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • orderIdstring · uuidrequiredOrder ID

Response · 200

  • idstring · uuidrequiredOrder ID
  • orderReferencestringrequired
  • statusstringrequiredOne of: new · paid · in_progress · delivered · completed · cancelled
  • displayStatusstringrequiredSeller-facing status label
  • slaFlaggedbooleanrequiredTrue while the order is still Paid after the two-business-day processing SLA elapsed (J5.4); clears when the order advances or is cancelled.
  • elapsedBusinessDaysintegerBusiness days (Mon-Fri) since payment; null unless the order is Paid.
  • slaThresholdBusinessDaysintegerrequiredPlatform processing SLA in business days (2).
  • customerIdentityobjectrequired
    • customerIdstringrequiredBuyer marketplace user id
    • namestring
    • emailstring
    • phonestring
  • itemsarray<object>required
    • idstringrequired
    • chosenItemLabelstringrequiredProduct title with variant description
    • imageUrlstring
    • quantityintegerrequired
    • unitPriceintegerrequiredUnit price in cents
    • lineTotalintegerrequiredLine total in cents
    • currencystringrequired
    • shipmentIdstring
    • skustring
    • barcodestring
    • weightGramsintegerItem weight in grams
    • lengthMmintegerItem length in millimeters
    • widthMmintegerItem width in millimeters
    • heightMmintegerItem height in millimeters
  • shipmentsarray<object>required
    • idstring · uuidrequiredShipment ID
    • sequenceNumberintegerrequiredShipment sequence (1-based)
    • totalShipmentsintegerrequiredTotal number of shipments in the order
    • statusstringrequiredShipment status machine valueOne of: pending · processed · shipped · delivered
    • displayStatusstringrequiredHuman-readable shipment status (varies by fulfillment method)
    • fulfillmentMethodstringrequiredOne of: delivery · pickup · locker
    • methodNamestringShipping method name. On a pickup shipment it holds the pickup location's name, so show it as a place, not as a shipping method.
    • carrierCodestringRegistry carrier code (set when a carrier is resolved)
    • carrierNamestringCarrier name
    • deliveryCostintegerrequiredDelivery cost in cents for this shipment
    • currencystringrequired
    • estimatedDeliveryDatestring · dateEstimated delivery date (YYYY-MM-DD)
    • trackingNumberstringTracking number (set when shipment advances to Shipped)
    • trackingUrlstringCarrier tracking URL, resolved at read time from the carrier registry template. Null when the carrier, template, or tracking number is missing.
    • carrierPortalUrlstringCarrier self-service portal URL (seller-only; locker shipments)
  • priceBreakdownobjectrequiredWhat the customer paid, per component. There is no discount line: each component is already net of its coupon, so `orderTotal` is always `itemsSubtotal + totalDeliveryCost` and equals the amount charged.
    • itemsSubtotalintegerrequiredSum of all item line totals in cents — after an items or whole-order coupon.
    • totalDeliveryCostintegerrequiredSum of all shipment delivery costs in cents, after a delivery coupon. Each shipment's own `deliveryCost` stays the fee before the coupon.
    • orderTotalintegerrequiredThe amount charged, in cents (itemsSubtotal + totalDeliveryCost).
    • currencystringrequiredISO 4217 currency code
  • paymentobjectPayment summary. Null when the order has no payment rows yet.
    • statusstringrequiredCanonical effective-payment status. `awaiting_settlement` means the buyer's money has left their bank and has not arrived yet: the order is held open with no deadline, and neither a retry nor a cancellation is offered while it lasts. Never…One of: pending · awaiting_settlement · paid · failed · expired
    • statusAtstring · date-timerequiredTimestamp when the payment reached its current status (terminal-safe)
  • cancellationobjectCancellation details (null when order is not cancelled)
    • actorstringWho cancelled the order. Populated for every cancellation the platform records; null only for orders cancelled before the actor was persisted.One of: customer · seller · system
    • reasonstringThe seller's own words, verbatim including line breaks. Present only when `actor` is `seller`; null for `customer` and `system` cancellations (a system cancellation's internal note is not exposed).
    • cancelledAtstring · date-timerequired
  • customerNotestring
  • deliveryAddressobjectTyped shipping-address snapshot echoed from the order, discriminated on `type`. Null only when the order carries no snapshot. One of 3 variants.
    • typestringrequiredSnapshot discriminator
    • recipientNamestringDelivery recipient captured with the order (order-level contact, not the address book)
    • streetAddressstringStreet address line
    • apartmentstringApartment / flat / unit number, snapshotted from the delivery address
    • citystring
    • postalCodestring
    • countryCodestringISO 3166-1 alpha-2 country code
    • courierNotestringFree-text courier note, snapshotted from the delivery address
    • mapPinLatnumber · floatDelivery map pin latitude, snapshotted from the delivery address
    • mapPinLngnumber · floatDelivery map pin longitude, snapshotted from the delivery address
    • contactPhonestringCourier-facing contact phone captured with the order (order-level contact)
    • contactEmailstringContact email captured with the order
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/orders/01914d0e-a3b4-75c6-97d8-43546576879a
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "orderReference": "MKT-2026-A3F9K2",
  "status": "new",
  "displayStatus": "In progress",
  "slaFlagged": false,
  "elapsedBusinessDays": 3,
  "slaThresholdBusinessDays": 2,
  "customerIdentity": {
    "customerId": "Customer id",
    "name": "Name",
    "email": "Email",
    "phone": "Phone"
  },
  "items": [
    {
      "id": "Id",
      "chosenItemLabel": "Chosen item label",
      "imageUrl": "Image url",
      "quantity": 0,
      "unitPrice": 2499,
      "lineTotal": 4998,
      "currency": "EUR",
      "shipmentId": "Shipment id",
      "sku": "Sku",
      "barcode": "Barcode",
      "weightGrams": 0,
      "lengthMm": 0,
      "widthMm": 0,
      "heightMm": 0
    }
  ],
  "shipments": [
    {
      "id": "01914d0e-7081-7293-a4a5-102132435467",
      "sequenceNumber": 1,
      "totalShipments": 2,
      "status": "pending",
      "displayStatus": "Shipped",
      "fulfillmentMethod": "delivery",
      "methodName": "Method name",
      "carrierCode": "Carrier code",
      "carrierName": "Carrier name",
      "deliveryCost": 499,
      "currency": "EUR",
      "estimatedDeliveryDate": "2026-09-10",
      "trackingNumber": "LP123456789LT",
      "trackingUrl": "Tracking url",
      "carrierPortalUrl": "Carrier portal url"
    }
  ],
  "priceBreakdown": {
    "itemsSubtotal": 4998,
    "totalDeliveryCost": 499,
    "orderTotal": 5497,
    "currency": "EUR"
  },
  "payment": {
    "status": "pending",
    "statusAt": "2026-09-10T09:24:11Z"
  },
  "cancellation": {
    "actor": "customer",
    "reason": "Reason",
    "cancelledAt": "2026-09-10T09:24:11Z"
  },
  "customerNote": "Customer note",
  "deliveryAddress": {
    "type": "Type",
    "recipientName": "Recipient name",
    "streetAddress": "Street address",
    "apartment": "Apartment",
    "city": "City",
    "postalCode": "Postal code",
    "countryCode": "Country code",
    "courierNote": "Courier note",
    "mapPinLat": 0,
    "mapPinLng": 0,
    "contactPhone": "Contact phone",
    "contactEmail": "Contact email"
  },
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
GET/rest/v1/purchase/stores/{storeId}/orders/{orderId}/timelineorders:readGet seller order timeline

Returns the curated activity timeline of a seller's order (oldest first): order-lifecycle and payment milestones sourced from the Activity Ledger, with internal-plumbing events filtered out. The ledger is eventually consistent (records…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • orderIdstring · uuidrequiredOrder ID

Query parameters

  • limitintegerMaximum number of timeline entries to return, oldest first (1-100).

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequiredActivity Ledger record ID
    • typestringrequiredCurated timeline event typeOne of: order_created · order_paid · order_delivered · order_completed · order_cancelled · shipment_advanced · payment_confirmed · payment_failed
    • occurredAtstring · date-timerequiredWhen the underlying event occurred
    • actorobjectrequiredWho triggered the event
    • transitionobjectrequiredStatus change carried by the entry. Null unless the entry's type is a transition (e.g. a shipment advance).
    • providerstringrequiredPayment provider key. Null unless the entry is a payment record.
  • _metadataobjectrequired
    • limitintegerrequiredRequested page size (echoes the `limit` query parameter)
    • hasMorebooleanrequiredTrue when the order has more timeline records than the returned page
    • timelineAvailablebooleanrequiredFalse when the Activity Ledger was unreachable — `items` is then empty and the read still returns 200 (never 503).

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/orders/01914d0e-c5d6-77e8-b9fa-6576879aabbc/timeline
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "type": "order_created",
      "occurredAt": "2026-09-10T09:24:11Z",
      "actor": {
        "kind": "customer",
        "displayName": "Display name"
      },
      "transition": {
        "from": "From",
        "to": "To"
      },
      "provider": "paysera_checkout"
    }
  ],
  "_metadata": {
    "limit": 100,
    "hasMore": false,
    "timelineAvailable": true
  }
}
read#
POST/rest/v1/purchase/stores/{storeId}/orders/{orderId}/cancelorders:read_writeCancel order as seller

Cancels an order as a seller. Requires a reason (5-1000 characters). Evaluates stock release based on the Possession Principle: goods still with the seller are released back to stock. Store ownership is enforced: a missing order, or a…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • orderIdstring · uuidrequiredOrder ID

Request body · application/json

  • reasonstringrequiredReason for cancellation (5-1000 characters)

Response · 200

  • orderIdstring · uuidrequired
  • orderReferencestringrequired
  • statusstringrequired
  • displayStatusstringrequired
  • previousStatusstringrequiredOrder status before cancellation
  • cancellationobjectrequired
    • actorstringrequiredOne of: customer · seller · system
    • reasonstringPresent only when `actor` is `seller`; a customer cancellation echoes null.
    • cancelledAtstring · date-timerequired
  • stockReleasedbooleanrequiredWhether committed stock was released back to inventory

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/purchase/stores/01914d0e-4d5e-7f60-b172-8d9e0f102134/orders/01914d0e-b4c5-76d7-a8e9-546576879aab/cancel
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": "Items damaged in warehouse"
}
jsonResponse · 200
{
  "orderId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "orderReference": "MKT-2026-ABCD",
  "status": "cancelled",
  "displayStatus": "Cancelled",
  "previousStatus": "paid",
  "cancellation": {
    "actor": "customer",
    "reason": "Items damaged in warehouse",
    "cancelledAt": "2026-09-10T09:24:11Z"
  },
  "stockReleased": false
}
write#
GET/rest/v1/purchase/stores/{storeId}/orders/countsorders:readSeller order counts

Per-tab order counts plus the sidebar-actionable rollup for the store's Orders view. Read-only, scoped to the store in the path. Buckets map the platform order statuses to the seller's vocabulary: `pending` counts Paid orders (awaiting the…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID

Response · 200

  • allintegerrequiredEvery order for the store — matches the unfiltered Orders list, so it also counts unpaid ('new') orders. NOT the sum of the four buckets below whenever the store has unpaid orders.
  • pendingintegerrequiredOrders in Paid status, awaiting the seller's first fulfillment action.
  • activeintegerrequiredOrders in In Progress or Delivered status.
  • completedintegerrequiredOrders in Completed status.
  • cancelledintegerrequiredOrders in Cancelled status.
  • refundsobjectrequired
    • qualifyingOrderCountintegerrequiredOrders with a qualifying refund request. Reported as 0 today — refund requests are not modelled server-side yet.
  • sidebarActionableintegerrequiredCount driving the sidebar Orders badge. Equals the pending (Paid) count, and that is the exact answer rather than an approximation: an order is SLA-breached only while it is still Paid, so the SLA component is a strict subset of the paid…

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-8192-73a4-b5b6-213243546578/orders/counts
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "all": 63,
  "pending": 12,
  "active": 7,
  "completed": 40,
  "cancelled": 1,
  "refunds": {
    "qualifyingOrderCount": 0
  },
  "sidebarActionable": 12
}
read#
GET/rest/v1/purchase/stores/{storeId}/orders/summaryorders:readSeller sales summary

Sales summary of the store over the half-open period [from, to): revenue, order count, items sold, average order value, one zero-filled entry per calendar day of the period in `timeZone` (ascending), and the five best-selling listing…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID

Query parameters

  • fromstring · date-timerequiredPeriod start, inclusive. An ISO-8601 instant with an offset, with a four-digit year of 1000 or later, and on or after 1970-01-01T00:00:00Z.
  • tostring · date-timerequiredPeriod end, exclusive. An ISO-8601 instant with an offset, after `from`, at most 366 days later, and with its last included moment on or before 9999-12-31 in `timeZone`.
  • timeZonestringIANA time zone the daily buckets follow.

Response · 200

  • currencystringrequired
  • revenueobjectrequired
    • amountCentsintegerrequiredAmount in cents (the smallest currency unit).
    • currencystringrequiredISO 4217 currency code.
  • orderCountintegerrequiredPaid-and-beyond orders placed in the period.
  • itemsSoldintegerrequiredSum of item quantities of the counted orders.
  • averageOrderValueobjectrequired`revenue` / `orderCount`, rounded to the cent; null when `orderCount` is 0.
    • amountCentsintegerrequiredAmount in cents (the smallest currency unit).
    • currencystringrequiredISO 4217 currency code.
  • dailyarray<object>requiredOne entry per calendar day of the period in `timeZone`, ascending, zero-filled.
    • datestring · daterequiredCalendar day in the requested time zone.
    • revenueobjectrequired
    • orderCountintegerrequired
  • topProductsarray<object>requiredUp to five variants, by `lineTotal` then `unitsSold`, descending.
    • listingVariantIdstringrequiredThe listing variant the order lines were bought as (order lines carry no listing id).
    • titlestringrequiredItem title from the most recent order line snapshot.
    • variantDescriptionstringrequiredVariant description from the most recent order line snapshot.
    • lineTotalobjectrequiredSum of the variant's order line totals — after item and order discounts, before delivery and delivery discounts. Not a share of the headline `revenue`.
    • unitsSoldintegerrequired

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-6f70-7182-9394-0f1021324356/orders/summary?from=2026-09-10T09%3A24%3A11Z&to=2026-09-10T09%3A24%3A11Z
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "currency": "EUR",
  "revenue": {
    "amountCents": 129900,
    "currency": "EUR"
  },
  "orderCount": 11,
  "itemsSold": 14,
  "averageOrderValue": {
    "amountCents": 129900,
    "currency": "EUR"
  },
  "daily": [
    {
      "date": "2026-11-04",
      "revenue": {
        "amountCents": 129900,
        "currency": "EUR"
      },
      "orderCount": 3
    }
  ],
  "topProducts": [
    {
      "listingVariantId": "01961d2c-0000-7000-8000-0000000000a1",
      "title": "iPhone 17 Pro Max",
      "variantDescription": "256 GB, Deep Blue",
      "lineTotal": {
        "amountCents": 129900,
        "currency": "EUR"
      },
      "unitsSold": 4
    }
  ]
}
read#

Order Shipments 1 operation

POST/rest/v1/purchase/stores/{storeId}/orders/{orderId}/shipments/{shipmentId}/advanceorders:read_writeAdvance shipment to next status

Advances a shipment to the next fulfillment status: Pending -> Processed -> Shipped -> Delivered. The `trackingNumber` field is optional and only meaningful when advancing to Shipped status. The request body itself is optional; omit it…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • orderIdstring · uuidrequiredOrder ID
  • shipmentIdstring · uuidrequiredShipment ID

Request body · application/json

  • trackingNumberstringTracking number for the shipment. Only meaningful when advancing to Shipped status.
  • carrierCodestringRegistry carrier code for a courier shipment (one of the integrated networks). Applied only when advancing to Shipped. Mutually exclusive with a free-text carrierName. Not accepted on locker/pickup shipments (carrier is method-derived).
  • carrierNamestringFree-text carrier name for a non-integrated ("Other") courier. Applied only when advancing to Shipped, and only when no carrierCode is given.

Response · 200

  • shipmentIdstring · uuidrequired
  • orderIdstring · uuidrequired
  • shipmentStatusstringrequiredNew shipment status after advanceOne of: pending · processed · shipped · delivered
  • shipmentDisplayStatusstringrequiredHuman-readable shipment status
  • previousStatusstringrequiredShipment status before the advance
  • trackingNumberstring
  • orderStatusstringrequiredCurrent order status (may have changed due to derived transitions)One of: new · paid · in_progress · delivered · completed · cancelled
  • orderDisplayStatusstringrequiredHuman-readable order status
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/purchase/stores/01914d0e-a3b4-75c6-97d8-43546576879a/orders/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/shipments/01914d0e-5e6f-7071-8283-9e0f10213245/advance
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "trackingNumber": "LP123456789LT",
  "carrierCode": "omniva",
  "carrierName": "Local courier"
}
jsonResponse · 200
{
  "shipmentId": "01914d0e-92a3-74b5-86c7-324354657689",
  "orderId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "shipmentStatus": "pending",
  "shipmentDisplayStatus": "Shipped",
  "previousStatus": "processed",
  "trackingNumber": "LP123456789LT",
  "orderStatus": "new",
  "orderDisplayStatus": "In progress",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#

Seller Coupons 1 operation

GET/rest/v1/purchase/stores/{storeId}/coupons/{couponId}/redemptionspromotions:readList seller coupon redemptions

Returns a store coupon's realized redemptions (captured coupon applications) with cursor-based pagination, newest redemption first, plus a `summary` realized rollup (total discount given, last redemption, redemption count). svc-purchase…

Requires

promotions:read

Path parameters

  • storeIdstring · uuidrequired
  • couponIdstring · uuidrequired

Query parameters

  • afterstring · uuid
  • beforestring · uuid
  • limitinteger

Response · 200

  • itemsarray<object>required
    • orderIdstring · uuid
    • orderReferencestring
    • redeemedAtstring · date-time
    • buyerNamestring
    • discountAmountintegerRealized discount in cents
  • _metadataobjectrequiredCursor-based pagination metadata
    • limitintegerrequiredRequested page size (echoed back)
    • hasMorebooleanrequiredWhether more items exist beyond this page
    • nextCursorstring · uuidUUID to pass as `?after=` for the next page
    • prevCursorstring · uuidUUID to pass as `?before=` for the previous page
    • totalCountintegerTotal item count (only when `includeTotalCount=true`)
  • summaryobjectrequiredThe realized rollup over the full captured set — purchase's side of the coupon ledger (summed realized discount, latest redemption, redemption count over CAPTURED applications only). Showroom stays authoritative for the coupon's usage…
    • discountGivenintegerSummed realized discount in cents
    • lastUsedAtstring · date-time
    • redemptionCountinteger

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/coupons/01914d0e-7081-7293-a4a5-102132435467/redemptions
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "orderId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "orderReference": "MKT-2026-000123",
      "redeemedAt": "2026-08-18T12:34:56.789012Z",
      "buyerName": "Jonas Jonaitis",
      "discountAmount": 1500
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
    "prevCursor": "01914d0e-b4c5-76d7-a8e9-546576879aab",
    "totalCount": 129900
  },
  "summary": {
    "discountGiven": 12500,
    "lastUsedAt": "2026-08-18T12:34:56.789012Z",
    "redemptionCount": 8
  }
}
read#

Seller Customers 8 operations

GET/rest/v1/purchase/stores/{storeId}/customersorders:readList store customers

Lists a store's customers -- buyers with at least one non-cancelled order -- with a case-insensitive substring search over the latest-order recipient name or contact email, case-insensitive AND-combined tag filtering, sorting, and…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID

Query parameters

  • searchstringCase-insensitive substring over the latest-order recipient name or contact email
  • tagsarray<string>Tag label to filter by. Repeat the parameter to filter by multiple tags (`?tags=VIP&tags=Wholesale`); the semantics are AND, matched case-insensitively.
  • sortBystringSort field (default lastOrderAt)One of: orderCount · lifetimeSpend · lastOrderAt
  • sortDirstringSort direction (default desc)One of: asc · desc
  • cursorstringOpaque forward-only cursor from a previous page's `_metadata.nextCursor`
  • limitintegerPage size (1-100, default 20)

Response · 200

  • itemsarray<object>required
    • idstringrequiredBuyer marketplace user id (opaque, not a UUID)
    • displayNamestringrequiredRecipient name from the buyer's latest-order shipping snapshot (falls back to the contact email, then an empty string)
    • emailstringrequiredContact email from the buyer's latest-order shipping snapshot
    • tagsarray<string>requiredLabels applied to this customer, ordered case-insensitively
    • orderCountintegerrequiredCount of the buyer's non-cancelled orders in the store
    • lifetimeSpendobjectrequiredA monetary amount in minor units (cents) plus its ISO 4217 currency
    • lastOrderAtstring · date-timerequiredPlacement time of the most recent non-cancelled order
    • firstOrderAtstring · date-timerequiredPlacement time of the earliest non-cancelled order
  • storeTagsarray<object>requiredThe store's full tag vocabulary with live per-tag customer counts
    • labelstringrequiredTag label
    • customerCountintegerrequiredNumber of the store's customers currently carrying this tag
  • _metadataobjectrequiredKeyset pagination metadata. Cursors are opaque forward-only base64url tokens (not UUIDs). `totalCount` is always computed for this list.
    • limitintegerrequiredRequested page size (echoed back)
    • hasMorebooleanrequiredWhether more items exist beyond this page
    • nextCursorstringOpaque cursor to pass as `?cursor=` for the next page; null on the last page
    • prevCursorstringOpaque cursor for the previous page (null on a forward-only first page)
    • totalCountintegerTotal number of customers matching the filters (always computed for this list)

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-5e6f-7071-8283-9e0f10213245/customers
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "Id",
      "displayName": "Display name",
      "email": "Email",
      "tags": [
        "Tags"
      ],
      "orderCount": 0,
      "lifetimeSpend": {
        "amountCents": 12999,
        "currency": "EUR"
      },
      "lastOrderAt": "2026-09-10T09:24:11Z",
      "firstOrderAt": "2026-09-10T09:24:11Z"
    }
  ],
  "storeTags": [
    {
      "label": "VIP",
      "customerCount": 0
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "Next cursor",
    "prevCursor": "Prev cursor",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/purchase/stores/{storeId}/customers/{customerId}orders:readGet customer detail

Returns a single customer's detail -- the aggregated rollup, the seller's notes and contacts, recent orders (max five), and the total paid-order count. Average order value is derived client-side (no `avgOrder` field). A buyer with no…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • customerIdstringrequiredBuyer marketplace user id (opaque string, not a UUID)

Response · 200

  • idstringrequiredBuyer marketplace user id (opaque, not a UUID)
  • displayNamestringrequired
  • emailstringrequired
  • tagsarray<string>required
  • orderCountintegerrequiredCount of the buyer's non-cancelled orders in the store
  • lifetimeSpendobjectrequiredA monetary amount in minor units (cents) plus its ISO 4217 currency
    • amountCentsintegerrequiredAmount in cents
    • currencystringrequiredISO 4217 currency code
  • lastOrderAtstring · date-timerequired
  • firstOrderAtstring · date-timerequired
  • notesstringrequiredThe seller's private note. Empty string when absent or saved-empty -- never null.
  • contactsarray<object>required
    • idstringrequiredServer-minted contact id
    • namestringrequired
    • emailstringrequired
    • phonestringrequired
  • recentOrdersarray<object>requiredThe buyer's newest non-cancelled orders (max five)
    • orderIdstring · uuidrequired
    • orderReferencestringrequired
    • placedAtstring · date-timerequired
    • itemCountintegerrequired
    • fulfilmentstringRaw fulfilment method of the first shipment; null when the order has no shipment yetOne of: delivery · pickup · locker
    • totalobjectrequiredA monetary amount in minor units (cents) plus its ISO 4217 currency
  • totalPaidOrdersintegerrequiredCount of the buyer's paid-and-beyond orders (Paid, In Progress, Delivered, Completed)

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-7081-7293-a4a5-102132435467/customers/Customer id
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "displayName": "Display name",
  "email": "Email",
  "tags": [
    "Tags"
  ],
  "orderCount": 0,
  "lifetimeSpend": {
    "amountCents": 12999,
    "currency": "EUR"
  },
  "lastOrderAt": "2026-09-10T09:24:11Z",
  "firstOrderAt": "2026-09-10T09:24:11Z",
  "notes": "Notes",
  "contacts": [
    {
      "id": "Id",
      "name": "Name",
      "email": "Email",
      "phone": "Phone"
    }
  ],
  "recentOrders": [
    {
      "orderId": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "orderReference": "MKT-2026-A3F9K2",
      "placedAt": "2026-09-10T09:24:11Z",
      "itemCount": 0,
      "fulfilment": "delivery",
      "total": {
        "amountCents": 12999,
        "currency": "EUR"
      }
    }
  ],
  "totalPaidOrders": 129900
}
read#
GET/rest/v1/purchase/stores/{storeId}/customers/{customerId}/ordersorders:readGet customer recent orders

Returns the customer's newest non-cancelled orders (max five) as a plain `{items}` envelope -- order reference, placement time, item count, first-shipment fulfilment method, and total. A buyer with no non-cancelled order in the store is a…

Requires

orders:read

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • customerIdstringrequiredBuyer marketplace user id (opaque string, not a UUID)

Response · 200

  • itemsarray<object>required
    • orderIdstring · uuidrequired
    • orderReferencestringrequired
    • placedAtstring · date-timerequired
    • itemCountintegerrequired
    • fulfilmentstringRaw fulfilment method of the first shipment; null when the order has no shipment yetOne of: delivery · pickup · locker
    • totalobjectrequiredA monetary amount in minor units (cents) plus its ISO 4217 currency

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-b4c5-76d7-a8e9-546576879aab/customers/Customer id/orders
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "orderId": "01914d0e-8192-73a4-b5b6-213243546578",
      "orderReference": "MKT-2026-A3F9K2",
      "placedAt": "2026-09-10T09:24:11Z",
      "itemCount": 0,
      "fulfilment": "delivery",
      "total": {
        "amountCents": 12999,
        "currency": "EUR"
      }
    }
  ]
}
read#
PUT/rest/v1/purchase/stores/{storeId}/customers/{customerId}/notesorders:read_writeRecord buyer note

Writes (or overwrites) the seller's private note about a buyer. The empty string saves an explicitly-empty note; use DELETE to remove the note entirely. Requires the `orders:read_write` capability (the Orders area at read-write level).

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • customerIdstringrequiredBuyer marketplace user id (opaque string, not a UUID)

Request body · application/json

  • notesstringrequiredThe seller's private note about the buyer. The empty string is allowed and saves an explicitly-empty note (distinct from deleting the note via DELETE).

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/purchase/stores/01914d0e-5e6f-7071-8283-9e0f10213245/customers/Customer id/notes
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "notes": "Prefers pickup on weekdays. Repeat buyer."
}
write#
DELETE/rest/v1/purchase/stores/{storeId}/customers/{customerId}/notesorders:read_writeClear buyer note

Deletes the seller's private note about a buyer. Idempotent -- returns 204 even when no note exists. Requires the `orders:read_write` capability (the Orders area at read-write level).

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • customerIdstringrequiredBuyer marketplace user id (opaque string, not a UUID)

Response · 204

No content.

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/purchase/stores/01914d0e-5e6f-7071-8283-9e0f10213245/customers/Customer id/notes
Authorization: Bearer $TOKEN
write#
POST/rest/v1/purchase/stores/{storeId}/customers/{customerId}/tagsorders:read_writeApply customer tag

Applies a tag to a buyer. With `createIfMissing=false` (default) an unknown label returns 404; with `createIfMissing=true` the label is reused (case-insensitively) or created, then applied. Applying is idempotent. Requires the…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • customerIdstringrequiredBuyer marketplace user id (opaque string, not a UUID)

Request body · application/json

  • labelstringrequiredThe tag label to apply. Matched against the store vocabulary case-insensitively.
  • createIfMissingbooleanWhen false (default), an unknown label is rejected with 404. When true, the label is reused case-insensitively or minted into the store vocabulary, then applied.

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/purchase/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/customers/Customer id/tags
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "label": "VIP",
  "createIfMissing": false
}
write#
DELETE/rest/v1/purchase/stores/{storeId}/customers/{customerId}/tagsorders:read_writeWithdraw customer tag

Removes an applied tag from a buyer by label (case-insensitive). The label travels in the `label` query parameter, so it may hold any character a label can, "/" and "\" included. Idempotent -- returns 204 even when the tag was not applied…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • customerIdstringrequiredBuyer marketplace user id (opaque string, not a UUID)

Query parameters

  • labelstringrequiredThe tag label to withdraw, matched case-insensitively

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/purchase/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/customers/Customer id/tags?label=Label
Authorization: Bearer $TOKEN
write#
PUT/rest/v1/purchase/stores/{storeId}/customers/{customerId}/contactsorders:read_writeReplace customer contacts

Set-replaces the buyer's ordered contact list (max 20). Position is significant -- the first card is the main contact. The server mints contact ids; any inbound ids are ignored. An empty list clears all contacts. Requires the…

Requires

orders:read_write

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • customerIdstringrequiredBuyer marketplace user id (opaque string, not a UUID)

Request body · application/json

  • contactsarray<object>requiredThe full ordered contact list (set-replace). Position is significant -- the first card is the main contact. An empty list clears all contacts. The server mints contact ids; any inbound ids are ignored.
    • namestringrequiredContact name (required)
    • emailstringContact email (optional)
    • phonestringContact phone (optional)

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
PUT /rest/v1/purchase/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/customers/Customer id/contacts
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "contacts": [
    {
      "name": "Jonas Petraitis",
      "email": "jonas@example.com",
      "phone": "+37060000000"
    }
  ]
}
write#

Store Payment Providers 7 operations

GET/rest/v1/purchase/stores/{storeId}/payment-providersadministratorList store payment providers

Returns all payment providers connected to a store. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive 403 `/errors/forbidden`.

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore ID

Response · 200

  • itemsarray<object>requiredList of connected payment providers
    • providerstringrequiredProvider key
    • displayNamestringrequiredHuman-readable provider name
    • isDefaultbooleanrequiredWhether this is the default provider
    • enabledbooleanrequiredWhether the provider is enabled
    • credentialSchemaOutdatedbooleanrequiredWhether stored credentials use an older schema version
    • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)
    • updatedAtstring · date-timerequiredLast update timestamp (ISO 8601)

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-5e6f-7071-8283-9e0f10213245/payment-providers
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "provider": "paysera_checkout",
      "displayName": "Paysera Checkout",
      "isDefault": true,
      "enabled": true,
      "credentialSchemaOutdated": false,
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ]
}
read#
PUT/rest/v1/purchase/stores/{storeId}/payment-providers/{provider}administratorConnect or rotate payment provider

Connects a payment provider to a store or rotates existing credentials. Returns 201 for new connections, 200 for credential rotation. The submitted credentials are checked with the payment provider before anything is saved: for Paysera…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • providerstringrequiredPayment provider key

Request body · application/json

  • credentialsobjectrequiredProvider credentials as key-value pairs

Response · 200

  • providerstringrequiredProvider key
  • displayNamestringrequiredHuman-readable provider name
  • isDefaultbooleanrequiredWhether this is the default provider
  • enabledbooleanrequiredWhether the provider is enabled
  • credentialSchemaOutdatedbooleanrequiredWhether stored credentials use an older schema version
  • credentialSchemaVersionintegerrequiredCurrent schema version of the stored credentials
  • credentialFieldsarray<object>requiredCredential field definitions from the current schema
    • namestringrequiredField key
    • labelstringrequiredHuman-readable label
    • placeholderstringrequiredInput placeholder text
    • typestringrequiredField input typeOne of: text · secret
    • requiredbooleanrequiredWhether the field is mandatory
    • valuestringStored value for text fields; always empty for secret fields
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)
  • updatedAtstring · date-timerequiredLast update timestamp (ISO 8601)

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 502 · 503 — See the error reference

httpRequest
PUT /rest/v1/purchase/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/payment-providers/Provider
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "credentials": {
    "clientId": "platfrom-api-client-checkout-project-12345",
    "clientSecret": "your-client-secret"
  }
}
jsonResponse · 200
{
  "provider": "paysera_checkout",
  "displayName": "Paysera Checkout",
  "isDefault": true,
  "enabled": true,
  "credentialSchemaOutdated": false,
  "credentialSchemaVersion": 2,
  "credentialFields": [
    {
      "name": "clientId",
      "label": "Client ID",
      "placeholder": "platfrom-api-client-checkout-project-...",
      "type": "text",
      "required": true,
      "value": "platfrom-api-client-checkout-project-12345"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/purchase/stores/{storeId}/payment-providers/{provider}administratorGet store payment provider

Returns details for a specific payment provider connected to a store, including credential schema. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive 403…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • providerstringrequiredPayment provider key

Response · 200

  • providerstringrequiredProvider key
  • displayNamestringrequiredHuman-readable provider name
  • isDefaultbooleanrequiredWhether this is the default provider
  • enabledbooleanrequiredWhether the provider is enabled
  • credentialSchemaOutdatedbooleanrequiredWhether stored credentials use an older schema version
  • credentialSchemaVersionintegerrequiredCurrent schema version of the stored credentials
  • credentialFieldsarray<object>requiredCredential field definitions from the current schema
    • namestringrequiredField key
    • labelstringrequiredHuman-readable label
    • placeholderstringrequiredInput placeholder text
    • typestringrequiredField input typeOne of: text · secret
    • requiredbooleanrequiredWhether the field is mandatory
    • valuestringStored value for text fields; always empty for secret fields
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)
  • updatedAtstring · date-timerequiredLast update timestamp (ISO 8601)

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/payment-providers/Provider
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "provider": "paysera_checkout",
  "displayName": "Paysera Checkout",
  "isDefault": true,
  "enabled": true,
  "credentialSchemaOutdated": false,
  "credentialSchemaVersion": 2,
  "credentialFields": [
    {
      "name": "clientId",
      "label": "Client ID",
      "placeholder": "platfrom-api-client-checkout-project-...",
      "type": "text",
      "required": true,
      "value": "platfrom-api-client-checkout-project-12345"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
DELETE/rest/v1/purchase/stores/{storeId}/payment-providers/{provider}administratorRemove payment provider

Removes a payment provider from a store. Cannot remove the last enabled provider if the store is published. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • providerstringrequiredPayment provider key

Response · 204

No content.

Errors

401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
DELETE /rest/v1/purchase/stores/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/payment-providers/Provider
Authorization: Bearer $TOKEN
write#
POST/rest/v1/purchase/stores/{storeId}/payment-providers/{provider}/enableadministratorEnable payment provider

Enables a payment provider for a store. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive 403 `/errors/forbidden`.

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • providerstringrequiredPayment provider key

Response · 200

  • providerstringrequiredProvider key
  • displayNamestringrequiredHuman-readable provider name
  • isDefaultbooleanrequiredWhether this is the default provider
  • enabledbooleanrequiredWhether the provider is enabled
  • credentialSchemaOutdatedbooleanrequiredWhether stored credentials use an older schema version
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)
  • updatedAtstring · date-timerequiredLast update timestamp (ISO 8601)

Errors

401 · 403 · 404 · 409 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/purchase/stores/01914d0e-5e6f-7071-8283-9e0f10213245/payment-providers/Provider/enable
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "provider": "paysera_checkout",
  "displayName": "Paysera Checkout",
  "isDefault": true,
  "enabled": true,
  "credentialSchemaOutdated": false,
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/purchase/stores/{storeId}/payment-providers/{provider}/disableadministratorDisable payment provider

Disables a payment provider for a store. Cannot disable the last enabled provider if the store is published. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • providerstringrequiredPayment provider key

Response · 200

  • providerstringrequiredProvider key
  • displayNamestringrequiredHuman-readable provider name
  • isDefaultbooleanrequiredWhether this is the default provider
  • enabledbooleanrequiredWhether the provider is enabled
  • credentialSchemaOutdatedbooleanrequiredWhether stored credentials use an older schema version
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)
  • updatedAtstring · date-timerequiredLast update timestamp (ISO 8601)

Errors

401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/purchase/stores/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/payment-providers/Provider/disable
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "provider": "paysera_checkout",
  "displayName": "Paysera Checkout",
  "isDefault": true,
  "enabled": true,
  "credentialSchemaOutdated": false,
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
POST/rest/v1/purchase/stores/{storeId}/payment-providers/{provider}/defaultadministratorSet default payment provider

Sets an enabled payment provider as the default for a store. Clears the default flag from any other provider. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore ID
  • providerstringrequiredPayment provider key

Response · 200

  • providerstringrequiredProvider key
  • displayNamestringrequiredHuman-readable provider name
  • isDefaultbooleanrequiredWhether this is the default provider
  • enabledbooleanrequiredWhether the provider is enabled
  • credentialSchemaOutdatedbooleanrequiredWhether stored credentials use an older schema version
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)
  • updatedAtstring · date-timerequiredLast update timestamp (ISO 8601)

Errors

401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/purchase/stores/01914d0e-92a3-74b5-86c7-324354657689/payment-providers/Provider/default
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "provider": "paysera_checkout",
  "displayName": "Paysera Checkout",
  "isDefault": true,
  "enabled": true,
  "credentialSchemaOutdated": false,
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#

Payment Providers 2 operations

GET/rest/v1/payment-providersauthenticatedList payment provider catalogue

Returns all available payment providers that can be connected to a store.

Requires

authenticated

Response · 200

  • itemsarray<object>requiredList of available payment providers
    • providerstringrequiredProvider key
    • displayNamestringrequiredHuman-readable provider name
    • descriptionstringrequiredProvider description
    • docsUrlstringrequiredDocumentation URL
    • credentialFieldsarray<object>requiredCredential field definitions

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/payment-providers
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "provider": "paysera_checkout",
      "displayName": "Paysera Checkout",
      "description": "Cards, Apple Pay, Google Pay, SEPA, local banks",
      "docsUrl": "https://developers.paysera.com/guides/checkout-v3",
      "credentialFields": [
        {
          "name": "clientId",
          "label": "Client ID",
          "placeholder": "platfrom-api-client-checkout-project-...",
          "type": "text",
          "required": true
        }
      ]
    }
  ]
}
read#
GET/rest/v1/payment-providers/{provider}authenticatedGet payment provider details

Returns details for a specific payment provider from the catalogue.

Requires

authenticated

Path parameters

  • providerstringrequiredPayment provider key

Response · 200

  • providerstringrequiredProvider key
  • displayNamestringrequiredHuman-readable provider name
  • descriptionstringrequiredProvider description
  • docsUrlstringrequiredDocumentation URL
  • credentialFieldsarray<object>requiredCredential field definitions
    • namestringrequiredField key
    • labelstringrequiredHuman-readable label
    • placeholderstringrequiredInput placeholder text
    • typestringrequiredField input typeOne of: text · secret
    • requiredbooleanrequiredWhether the field is mandatory

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/payment-providers/Provider
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "provider": "paysera_checkout",
  "displayName": "Paysera Checkout",
  "description": "Cards, Apple Pay, Google Pay, SEPA, local banks",
  "docsUrl": "https://developers.paysera.com/guides/checkout-v3",
  "credentialFields": [
    {
      "name": "clientId",
      "label": "Client ID",
      "placeholder": "platfrom-api-client-checkout-project-...",
      "type": "text",
      "required": true
    }
  ]
}
read#

Payments 2 operations

GET/rest/v1/purchase/payments/{paymentId}authenticatedGet payment details

Returns the details of one of the caller's own payments — a payment for an order the signed-in buyer placed. A payment for another buyer's order answers 404, the same as an unknown id; a delegated buyer agent holding `ordering:read` is…

Requires

authenticated

Path parameters

  • paymentIdstring · uuidrequiredPayment ID

Response · 200

  • paymentIdstring · uuidrequiredPayment ID
  • orderIdstring · uuidrequiredOrder ID
  • storeIdstring · uuidrequiredStore ID
  • providerstringrequiredPayment provider key
  • externalOrderIdstringExternal payment order ID
  • amountintegerrequiredAmount in minor units (cents)
  • currencystringrequiredISO 4217 currency code
  • descriptionstringrequiredPayment description
  • statusstringrequiredPayment status. `awaiting_settlement` is the buyer's money in transit -- their bank has taken it and it has not arrived. It is not a failure and it has no deadline; a payment in this state cannot be retried and its order cannot be…One of: pending · awaiting_settlement · paid · failed · expired
  • redirectUrlstringURL to redirect customer for payment
  • createdAtstring · date-timerequiredCreation timestamp (ISO 8601)
  • updatedAtstring · date-timerequiredLast update timestamp (ISO 8601)

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/payments/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "paymentId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "orderId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
  "storeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "provider": "paysera_checkout",
  "externalOrderId": "External order id",
  "amount": 1999,
  "currency": "EUR",
  "description": "Description",
  "status": "pending",
  "redirectUrl": "Redirect url",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
GET/rest/v1/purchase/payments/{paymentId}/returnpublicPayment return after provider redirect

Redirects to `{frontendUrl}/{locale}/checkout/confirmation/{orderId}` in the language the order was placed in (`en` when unknown), or to the mobile deep link. Called by the buyer's browser after the provider redirect.

Requires

public

Path parameters

  • paymentIdstring · uuidrequiredPayment ID

Query parameters

  • statusstringProvider-reported status hintOne of: success · failure
  • platformstringTarget platform for the redirect — web (frontend URL) or mobile (deep link)One of: web · mobile

Errors

302 — See the error reference

httpRequest
GET /rest/v1/purchase/payments/01914d0e-b4c5-76d7-a8e9-546576879aab/return
Authorization: Bearer $TOKEN
read#

Payment Methods 1 operation

GET/rest/v1/purchase/payment-providers/{provider}/stores/{storeId}/methodsauthenticatedList available payment methods

Returns available payment methods for a specific provider and store.

Requires

authenticated

Path parameters

  • providerstringrequiredPayment provider key
  • storeIdstring · uuidrequiredStore ID

Query parameters

  • amountintegerAmount in minor units (cents) to filter methods by
  • currencystringISO 4217 currency code to filter methods by

Response · 200

  • itemsarray<object>requiredList of available payment methods
    • keystringPayment method key, as issued by the payment provider
    • titlestringrequiredHuman-readable title
    • descriptionstringMethod description
    • typestringrequiredMethod type. Observed values from Paysera Checkout: `pis` (payment initiation -- banks and the Paysera wallet), `card`, `bnpl`. Treat as an open vocabulary: the provider may add values.
    • flowstringrequiredPayment flow. Observed values from Paysera Checkout: `redirect`, `direct`. Treat as an open vocabulary.
    • availableCountriesarray<string>requiredISO 3166-1 alpha-2 codes of the countries the method is available in. Eligibility only -- it carries no display ordering.
    • availableCurrenciesobjectrequiredCurrencies the method accepts, keyed by ISO 4217 code. `main` marks the method's primary currency. An object, not an array of codes.
    • logoUrlstring · uriAbsolute URL of the method's official logo (48x48 SVG). Null when the method has no addressable logo. Fetch it from the buyer's browser -- the asset host rate limits per IP, so a server-side fetch throttles. Unknown keys return 200 with a…

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/purchase/payment-providers/Provider/stores/01914d0e-c5d6-77e8-b9fa-6576879aabbc/methods
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "key": "swedbank",
      "title": "Swedbank",
      "description": "Leading Nordic-Baltic bank.",
      "type": "pis",
      "flow": "redirect",
      "availableCountries": [
        "LV",
        "EE",
        "LT"
      ],
      "availableCurrencies": {
        "EUR": {
          "main": true
        }
      },
      "logoUrl": "https://api.paysera.com/checkout-engine/public/v1/assets/payment-method/swedbank/logo"
    }
  ]
}
read#

Payment Confirmation 2 operations

GET/rest/v1/customer/orders/{orderId}/confirmationauthenticatedGet order confirmation screen data

Returns enriched payment confirmation data for the post-checkout screen, keyed by order. Resolves the latest payment attempt for the order and includes order summary, screen type (success/failure/pending), remaining cart seller count, and…

Requires

authenticated

Path parameters

  • orderIdstring · uuidrequiredOrder ID

Response · 200

  • paymentIdstring · uuidrequiredPayment ID
  • orderIdstring · uuidrequiredOrder ID
  • screenTypestringrequiredConfirmation screen type -- determines which view to render. A payment whose money is still in transit (`awaiting_settlement`) reads as `pending`, so keep polling this endpoint for as long as `pending` comes back and show no deadline while…One of: success · pending · failure
  • orderSummaryobjectrequiredOrder summary shown on the confirmation screen
    • orderReferencestringrequiredHuman-readable order reference
    • storeIdstring · uuidrequiredStore ID (resolve store name at read time)
    • itemsarray<object>requiredOrder line items
    • fulfillmentMethodstringrequiredFulfillment method used for this order
    • deliveryAddressCitystringDelivery address city (null for pickup orders)
    • pickupLocationNamestringPickup location name (null for delivery orders)
    • deliveryCostintegerrequiredDelivery cost in cents
    • orderTotalintegerrequiredOrder total in cents (items + delivery)
    • currencystringrequiredISO 4217 currency code
  • remainingSellerCountintegerNumber of remaining seller groups in the cart still awaiting checkout. Null when the cart is empty.
  • availablePaymentMethodsarray<object>requiredAlways empty. svc-purchase returns `[]` for every screen type -- clients fetch retry options from `GET /rest/v1/purchase/payment-providers/{provider}/stores/{storeId}/methods`.
    • keystringrequiredPayment method key
    • titlestringrequiredHuman-readable method name
  • createdAtstring · date-timerequiredPayment creation timestamp (ISO 8601)

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/customer/orders/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/confirmation
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "paymentId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "orderId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "screenType": "success",
  "orderSummary": {
    "orderReference": "MKT-2026-A3F9K2",
    "storeId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "items": [
      {
        "title": "Running Shoes, Size 42 / Black",
        "quantity": 1,
        "pricePerUnit": 2499,
        "lineTotal": 2499,
        "currency": "EUR"
      }
    ],
    "fulfillmentMethod": "delivery",
    "deliveryAddressCity": "Delivery address city",
    "pickupLocationName": "Pickup location name",
    "deliveryCost": 499,
    "orderTotal": 5497,
    "currency": "EUR"
  },
  "remainingSellerCount": 0,
  "availablePaymentMethods": [
    {
      "key": "paysera",
      "title": "Paysera"
    }
  ],
  "createdAt": "2026-09-10T09:24:11Z"
}
read#
POST/rest/v1/customer/payments/{paymentId}/retryauthenticatedRetry payment with different method

Creates a new payment session for the same order. Only allowed when the order is still in New state (awaiting payment), no attempt on the order has already been paid, and no attempt is still being settled -- a buyer whose money is already…

Requires

authenticated

Path parameters

  • paymentIdstring · uuidrequiredPayment ID

Request body · application/json

  • paymentMethodKeystringrequiredPayment method key for the retry
  • paymentCountryCodestringISO 3166-1 alpha-2 country code

Response · 200

  • paymentRedirectUrlstringrequiredURL to redirect the customer for payment
  • paymentIdstring · uuidrequiredNew payment session ID

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/customer/payments/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/retry
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "paymentMethodKey": "paysera",
  "paymentCountryCode": "LT"
}
jsonResponse · 200
{
  "paymentRedirectUrl": "Payment redirect url",
  "paymentId": "01914d0e-4d5e-7f60-b172-8d9e0f102134"
}
write#

Auth 5 operations

POST/rest/v1/auth/registerpublicRegister a marketplace account

Mediated registration — an address the `marketplace` realm does not know yet gets a Keycloak account with the submitted password, and by the time this returns the frontend can sign in via the Direct Access Grant and provision the local DB…

Requires

public

Request body · application/json

  • emailstring · emailrequiredEmail address — the account identity anchor
  • passwordstringrequiredAccount password
  • displayNamestringrequiredDisplay name

Response · 202

  • statusstringrequiredNeutral acknowledgement — identical whether or not the address already has an account

Errors

403 · 422 · 500 · 502 · 503 — See the error reference

httpRequest
POST /rest/v1/auth/register
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "email": "buyer@example.com",
  "password": "sup3r-secret-pass",
  "displayName": "Jane Buyer"
}
jsonResponse · 202
{
  "status": "accepted"
}
write#
POST/rest/v1/auth/password-resetpublicRequest a password reset

Requests a password link for the given address. Always returns 202 Accepted with the same body, whether or not an account exists and whichever `audience` is named (no account-existence leak): the account lookup, the token and the letter…

Requires

public

Request body · application/json

  • emailstring · emailrequiredEmail address to send the password-reset link to. Matched without regard to letter case or surrounding spaces.
  • audiencestringWhich app asked. `seller` sends the seller password letter, linking to the seller dashboard; `buyer` (the default) sends the customer one, linking to the storefront. It selects the letter and the link only — it never checks a role.One of: seller · buyer
  • localestringThe language the app is showing. The letter is written in it when the letter exists in that language; without it, in the language the account chose.One of: en · lt · lv · et

Response · 202

  • statusstringNeutral acknowledgement — identical whether or not an account exists

Errors

422 · 500 — See the error reference

httpRequest
POST /rest/v1/auth/password-reset
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "email": "seller@example.com",
  "audience": "seller",
  "locale": "lt"
}
jsonResponse · 202
{
  "status": "accepted"
}
write#
POST/rest/v1/auth/password-reset/confirmpublicConfirm a password reset

Sets a new password with the single-use token from a password-reset link (the `token` in the link's URL fragment), then signs the account out of every session — access tokens already issued stay valid until they expire, at most 1 hour. A…

Requires

public

Request body · application/json

  • tokenstringrequiredThe token from the reset link (the `token` in its URL fragment). Any value that is not a live token gets the same invalid-link answer.
  • newPasswordstringrequiredThe new password. The realm password policy may refuse it (422 `password_policy` on this field).

Response · 204

No content.

Errors

422 · 500 · 502 — See the error reference

httpRequest
POST /rest/v1/auth/password-reset/confirm
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "token": "3f0c9a1e5b7d2c4e6a8b0d1f3e5c7a9b1d3f5e7c9a0b2d4f6e8a1c3e5b7d9f0a",
  "newPassword": "New password"
}
write#
POST/rest/v1/auth/passwordauthenticatedChange the authenticated user password

Sets a new password for the authenticated user in Keycloak. svc-passport verifies `currentPassword` with Keycloak itself before anything changes — a valid access token alone never changes a password — and sets the new password on the…

Requires

authenticated

Request body · application/json

  • currentPasswordstringrequiredThe password the user signs in with today. svc-passport verifies it with Keycloak before anything changes; one Keycloak does not accept is a 422 with code `invalid_credentials` on this field.
  • newPasswordstringrequiredNew password to set

Response · 204

No content.

Errors

401 · 403 · 422 · 500 · 502 — See the error reference

httpRequest
POST /rest/v1/auth/password
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "currentPassword": "Current password",
  "newPassword": "New password"
}
write#
POST/rest/v1/auth/token-exchangepublicExchange a Paysera OIDC token for a first-party Keycloak access token

Validates a Paysera OIDC token, resolves the account by the Paysera identity the token carries — the federated-identity link the marketplace Keycloak holds — and mints a first-party Keycloak access token via the RFC 7523 JWT Authorization…

Requires

public

Request body · application/json

  • tokenstringrequiredPaysera OIDC token to exchange for a first-party Keycloak access token

Response · 200

  • accessTokenstringrequiredFirst-party Keycloak access token for API authentication
  • refreshTokenstringrequiredAlways null, structurally — Keycloak's JWT Authorization Grant opens a transient session and hard-codes "no refresh token" for this grant (RFC 7521 §4.1). No configuration changes it; clients re-exchange the Paysera token on expiry.
  • uidstringrequiredMarketplace user identifier (Keycloak user id)
  • expiresInintegerrequiredAccess token TTL in seconds

Errors

401 · 422 · 500 · 502 — See the error reference

httpRequest
POST /rest/v1/auth/token-exchange
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "token": "Token"
}
jsonResponse · 200
{
  "accessToken": "Access token",
  "refreshToken": "Refresh token",
  "uid": "Uid",
  "expiresIn": 3600
}
write#

Viewer Access 2 operations

GET/rest/v1/auth/meauthenticatedGet the caller's identity

Projects the caller's own token into a stable identity object: `uid`, `email`, `displayName`, `realm` (which Keycloak realm minted the token), `principalKind` (`admin` · `user` · `agent`), and `agent`. For an administrator or a human user…

Requires

authenticated

Response · 200

  • uidstringrequiredMarketplace user id — the `uid` token claim, falling back to the Keycloak `sub`.
  • emailstring · emailrequired
  • displayNamestringrequired
  • realmstringrequiredThe Keycloak realm that minted the token.One of: marketplace · marketplace-backoffice
  • principalKindstringrequiredThe kind of principal the token represents. `admin` is a backoffice administrator, `user` a human marketplace user, `agent` a delegated (non-human) identity.One of: admin · user · agent
  • agentobjectrequiredThe delegated-agent projection — present (non-null) only when `principalKind` is `agent`; `null` for an administrator or a human user.
    • idstring · uuidrequiredThe agent's platform id.
    • clientIdstringrequiredThe agent's Keycloak OAuth client id (`agt_` prefix).
    • surfacestringrequiredThe surface the agent acts on.
    • statusstringrequiredThe agent's lifecycle status.
    • scopesobjectrequiredA buyer agent's granted scope per area, using the canonical buyer-scope wire names. Every area is always present. Ceilings differ per area: `browse_search`, `order_tracking`, and `profile_addresses` are read-only (`none` · `read`)…
    • expiresAtstring · date-timerequiredWhen the agent's grant expires, or `null` when it does not expire.
    • mandateobjectrequiredThe agent's spending mandate, or `null` when it holds none.

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/auth/me
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "uid": "01932a00-0000-7000-8000-0000000000a1",
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "realm": "marketplace",
  "principalKind": "user",
  "agent": {
    "id": "01932a00-0000-7000-8000-0000000000b2",
    "clientId": "agt_7f3c9d21",
    "surface": "buyer",
    "status": "active",
    "scopes": {
      "browse_search": "read",
      "cart_wishlist": "read_write",
      "ordering": "read_write",
      "order_tracking": "read",
      "profile_addresses": "read"
    },
    "expiresAt": "2026-11-01T00:00:00.000000Z",
    "mandate": {
      "perOrderCapAmount": 5000,
      "monthlyCapAmount": 50000,
      "currency": "EUR"
    }
  }
}
read#
GET/rest/v1/seller/access/meauthenticatedGet the caller's seller accounts and access

Returns every account the caller belongs to, so the seller cabinet can render its account switcher and gate its nav from a single resolved object. Each entry carries the account id, the caller's `membershipId` and `status`…

Requires

authenticated

Response · 200

  • accountsarray<object>required
    • accountUserIdstringrequiredThe account's platform user id (the account is the owner's user id).
    • membershipIdstring · uuidrequiredThe caller's seat on this account.
    • statusstringrequiredThe caller's membership status on this account — `suspended` seats are included, not omitted.One of: active · suspended · removed
    • isAdministratorbooleanrequiredThe caller's role grants team & payouts.
    • roleobjectrequired
    • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…

Errors

401 · 403 · 500 — See the error reference

httpRequest
GET /rest/v1/seller/access/me
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "accounts": [
    {
      "accountUserId": "01932a00-0000-7000-8000-0000000000a1",
      "membershipId": "01932a00-0000-7000-8000-000000000001",
      "status": "active",
      "isAdministrator": true,
      "role": {
        "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
        "name": "Administrator",
        "type": "preset",
        "createdFromPreset": "administrator"
      },
      "scope": {
        "type": "whole_account",
        "storeIds": []
      },
      "capabilities": {
        "products": "read_write",
        "orders": "read",
        "stock": "read_write",
        "pricing": "none",
        "promotions": "none",
        "activity": "read"
      }
    }
  ]
}
read#

Users 1 operation

POST/rest/v1/usersauthenticatedRegister or provision a user

Provisions the local DB user record after Keycloak authentication. Idempotent: returns 201 on first call, 200 with the existing user on subsequent calls. `preferredLocale` is stored only when this call creates the user — an existing user…

Requires

authenticated

Request body · application/json

  • displayNamestringDisplay name for the user. When sent, it must contain a non-whitespace character.
  • preferredLocalestringThe language the person signed up in. Stored only when this call creates the user; an already-registered user keeps theirs. Omit when unknown.One of: en · lt · lv · et

Response · 200

  • idstringUser ID (marketplace user id — the `uid` token claim, falling back to the Keycloak `sub`)
  • emailstringUser email address
  • displayNamestringDisplay name
  • preferredLocalestringThe language the user is written to in; null when it was never captured.One of: en · lt · lv · et
  • createdAtstring · date-timeAccount creation timestamp (ISO 8601)

Errors

401 · 403 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/users
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "displayName": "John Doe",
  "preferredLocale": "lt"
}
jsonResponse · 200
{
  "id": "abc123def456",
  "email": "user@example.com",
  "displayName": "John Doe",
  "preferredLocale": "lt",
  "createdAt": "2026-04-07T12:34:56.789012Z"
}
write#

Addresses 6 operations

GET/rest/v1/addressesauthenticatedList customer addresses

Returns the authenticated customer's saved delivery addresses as a cursor-paginated `{items, _metadata}` envelope, ordered most-recent first. A delegated agent reads the address book of the human it acts for only with the…

Requires

authenticated

Query parameters

  • afterstring · uuid
  • beforestring · uuid
  • limitinteger
  • includeTotalCountbooleanWhen true, the response `_metadata` includes `totalCount`.

Response · 200

  • itemsarray<object>
    • idstring · uuid
    • labelstringUser-defined label (e.g. Home, Work). Always present.
    • countryCodestringISO 3166-1 alpha-2
    • citystring
    • streetAddressstringStreet address including building
    • postalCodestring
    • apartmentstringApartment / flat / unit number
    • courierNotestringFree-text note for the courier
    • mapPinLatnumber · floatMap pin latitude (-90 to 90)
    • mapPinLngnumber · floatMap pin longitude (-180 to 180)
    • isDefaultboolean
    • createdAtstring · date-time
    • updatedAtstring · date-time
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerPresent only when includeTotalCount=true.

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/addresses
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "45fd7708-e5c3-7b81-a9bc-89e2b4ed41e5",
      "label": "Home",
      "countryCode": "LT",
      "city": "Vilnius",
      "streetAddress": "Gedimino pr. 15-3",
      "postalCode": "01103",
      "apartment": "12A",
      "courierNote": "Leave at the front desk",
      "mapPinLat": 54.687157,
      "mapPinLng": 25.279652,
      "isDefault": true,
      "createdAt": "2026-05-18T08:00:00.000000Z",
      "updatedAt": "2026-05-18T08:00:00.000000Z"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "prevCursor": "01914d0e-92a3-74b5-86c7-324354657689",
    "totalCount": 129900
  }
}
read#
POST/rest/v1/addressesauthenticatedCreate a delivery address

Creates a new address in the authenticated customer's address book. The first address automatically becomes the default. A maximum of 20 addresses per customer is enforced — the 21st create returns a standard `422 /errors/invalid-state` (a…

Requires

authenticated

Request body · application/json

  • labelstringrequiredUser-defined label (e.g. Home, Work). Required on create.
  • countryCodestringrequiredISO 3166-1 alpha-2 country code (uppercase)
  • citystringrequiredCity name
  • streetAddressstringrequiredStreet address including building
  • postalCodestringrequiredPostal/ZIP code
  • apartmentstringApartment / flat / unit number
  • courierNotestringFree-text note for the courier
  • mapPinLatnumber · floatLatitude of address map pin (-90 to 90)
  • mapPinLngnumber · floatLongitude of address map pin (-180 to 180)

Response · 201

  • idstring · uuid
  • labelstringUser-defined label (e.g. Home, Work). Always present.
  • countryCodestringISO 3166-1 alpha-2
  • citystring
  • streetAddressstringStreet address including building
  • postalCodestring
  • apartmentstringApartment / flat / unit number
  • courierNotestringFree-text note for the courier
  • mapPinLatnumber · floatMap pin latitude (-90 to 90)
  • mapPinLngnumber · floatMap pin longitude (-180 to 180)
  • isDefaultboolean
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/addresses
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "label": "Home",
  "countryCode": "LT",
  "city": "Vilnius",
  "streetAddress": "Gedimino pr. 1",
  "postalCode": "01103",
  "apartment": "12A",
  "courierNote": "Leave at the front desk",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652
}
jsonResponse · 201
{
  "id": "45fd7708-e5c3-7b81-a9bc-89e2b4ed41e5",
  "label": "Home",
  "countryCode": "LT",
  "city": "Vilnius",
  "streetAddress": "Gedimino pr. 15-3",
  "postalCode": "01103",
  "apartment": "12A",
  "courierNote": "Leave at the front desk",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isDefault": true,
  "createdAt": "2026-05-18T08:00:00.000000Z",
  "updatedAt": "2026-05-18T08:00:00.000000Z"
}
write#
GET/rest/v1/addresses/{addressId}authenticatedGet a delivery address

Returns a single address belonging to the authenticated customer. A delegated agent reads it only with the `profile_addresses:read` scope (`x-required-agent-scope`): a buyer agent without it receives `403`, and a seller agent receives…

Requires

authenticated

Path parameters

  • addressIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • labelstringUser-defined label (e.g. Home, Work). Always present.
  • countryCodestringISO 3166-1 alpha-2
  • citystring
  • streetAddressstringStreet address including building
  • postalCodestring
  • apartmentstringApartment / flat / unit number
  • courierNotestringFree-text note for the courier
  • mapPinLatnumber · floatMap pin latitude (-90 to 90)
  • mapPinLngnumber · floatMap pin longitude (-180 to 180)
  • isDefaultboolean
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/addresses/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "45fd7708-e5c3-7b81-a9bc-89e2b4ed41e5",
  "label": "Home",
  "countryCode": "LT",
  "city": "Vilnius",
  "streetAddress": "Gedimino pr. 15-3",
  "postalCode": "01103",
  "apartment": "12A",
  "courierNote": "Leave at the front desk",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isDefault": true,
  "createdAt": "2026-05-18T08:00:00.000000Z",
  "updatedAt": "2026-05-18T08:00:00.000000Z"
}
read#
PUT/rest/v1/addresses/{addressId}authenticatedReplace a delivery address

Full replacement of an address. The client sends the complete address, exactly as on create: `label`, `countryCode`, `city`, `streetAddress`, and `postalCode` are required; `apartment`, `courierNote`, and the map-pin pair are optional. Any…

Requires

authenticated

Path parameters

  • addressIdstring · uuidrequired

Request body · application/json

  • labelstringrequiredUser-defined label (e.g. Home, Work). Required on create.
  • countryCodestringrequiredISO 3166-1 alpha-2 country code (uppercase)
  • citystringrequiredCity name
  • streetAddressstringrequiredStreet address including building
  • postalCodestringrequiredPostal/ZIP code
  • apartmentstringApartment / flat / unit number
  • courierNotestringFree-text note for the courier
  • mapPinLatnumber · floatLatitude of address map pin (-90 to 90)
  • mapPinLngnumber · floatLongitude of address map pin (-180 to 180)

Response · 200

  • idstring · uuid
  • labelstringUser-defined label (e.g. Home, Work). Always present.
  • countryCodestringISO 3166-1 alpha-2
  • citystring
  • streetAddressstringStreet address including building
  • postalCodestring
  • apartmentstringApartment / flat / unit number
  • courierNotestringFree-text note for the courier
  • mapPinLatnumber · floatMap pin latitude (-90 to 90)
  • mapPinLngnumber · floatMap pin longitude (-180 to 180)
  • isDefaultboolean
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 — See the error reference

httpRequest
PUT /rest/v1/addresses/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "label": "Home",
  "countryCode": "LT",
  "city": "Vilnius",
  "streetAddress": "Gedimino pr. 1",
  "postalCode": "01103",
  "apartment": "12A",
  "courierNote": "Leave at the front desk",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652
}
jsonResponse · 200
{
  "id": "45fd7708-e5c3-7b81-a9bc-89e2b4ed41e5",
  "label": "Home",
  "countryCode": "LT",
  "city": "Vilnius",
  "streetAddress": "Gedimino pr. 15-3",
  "postalCode": "01103",
  "apartment": "12A",
  "courierNote": "Leave at the front desk",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isDefault": true,
  "createdAt": "2026-05-18T08:00:00.000000Z",
  "updatedAt": "2026-05-18T08:00:00.000000Z"
}
write#
DELETE/rest/v1/addresses/{addressId}authenticatedDelete a delivery address

Deletes an address from the authenticated customer's address book. If the deleted address was the default, the most recently created remaining address is promoted to default.

Requires

authenticated

Path parameters

  • addressIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 500 — See the error reference

httpRequest
DELETE /rest/v1/addresses/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
write#
POST/rest/v1/addresses/{addressId}/defaultauthenticatedSet default address

Sets the specified address as the customer's default delivery address. The previous default (if any) is automatically demoted. No request body.

Requires

authenticated

Path parameters

  • addressIdstring · uuidrequired

Response · 200

  • idstring · uuid
  • labelstringUser-defined label (e.g. Home, Work). Always present.
  • countryCodestringISO 3166-1 alpha-2
  • citystring
  • streetAddressstringStreet address including building
  • postalCodestring
  • apartmentstringApartment / flat / unit number
  • courierNotestringFree-text note for the courier
  • mapPinLatnumber · floatMap pin latitude (-90 to 90)
  • mapPinLngnumber · floatMap pin longitude (-180 to 180)
  • isDefaultboolean
  • createdAtstring · date-time
  • updatedAtstring · date-time

Errors

401 · 403 · 404 · 500 — See the error reference

httpRequest
POST /rest/v1/addresses/01914d0e-92a3-74b5-86c7-324354657689/default
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "45fd7708-e5c3-7b81-a9bc-89e2b4ed41e5",
  "label": "Home",
  "countryCode": "LT",
  "city": "Vilnius",
  "streetAddress": "Gedimino pr. 15-3",
  "postalCode": "01103",
  "apartment": "12A",
  "courierNote": "Leave at the front desk",
  "mapPinLat": 54.687157,
  "mapPinLng": 25.279652,
  "isDefault": true,
  "createdAt": "2026-05-18T08:00:00.000000Z",
  "updatedAt": "2026-05-18T08:00:00.000000Z"
}
write#

User Profile 4 operations

GET/rest/v1/users/meauthenticatedGet current user profile

Returns the authenticated user profile including display name and avatar URL. A delegated agent reads the profile of the human it acts for only with the `profile_addresses:read` scope (`x-required-agent-scope`): a buyer agent without it…

Requires

authenticated

Response · 200

  • idstringUser ID (marketplace user id — the `uid` token claim, falling back to the Keycloak `sub`)
  • emailstringUser email address
  • displayNamestringDisplay name
  • avatarUrlstringFull public URL of the user avatar
  • preferredLocalestringThe language the user is written to in; null when it was never captured (set at registration or by `PATCH /rest/v1/users/me`).One of: en · lt · lv · et
  • createdAtstring · date-timeAccount creation timestamp (ISO 8601)
  • updatedAtstring · date-timeLast update timestamp (ISO 8601)

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/users/me
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "abc123def456",
  "email": "user@example.com",
  "displayName": "John Doe",
  "avatarUrl": "https://storage.example.com/avatars/abc123.webp",
  "preferredLocale": "lt",
  "createdAt": "2026-04-07T12:34:56.789012Z",
  "updatedAt": "2026-04-07T12:34:56.789012Z"
}
read#
PATCH/rest/v1/users/meauthenticatedUpdate user profile

Revises the authenticated user profile: a new display name, a language switch (`preferredLocale`), or both. A field left out keeps its current value; an explicit `null` is rejected, so neither field can be cleared. A body naming neither…

Requires

authenticated

Request body · application/json

  • displayNamestringNew display name for the user. Must contain a non-whitespace character. Omit to keep the current one; null is rejected.
  • preferredLocalestringThe language to write to the user in — their language switch. Omit to keep the current one; null is rejected (a preferred locale can be changed, never cleared).One of: en · lt · lv · et

Response · 200

  • idstringUser ID (marketplace user id — the `uid` token claim, falling back to the Keycloak `sub`)
  • emailstringUser email address
  • displayNamestringDisplay name
  • avatarUrlstringFull public URL of the user avatar
  • preferredLocalestringThe language the user is written to in; null when it was never captured (set at registration or by `PATCH /rest/v1/users/me`).One of: en · lt · lv · et
  • createdAtstring · date-timeAccount creation timestamp (ISO 8601)
  • updatedAtstring · date-timeLast update timestamp (ISO 8601)

Errors

400 · 401 · 403 · 422 · 500 — See the error reference

httpRequest
PATCH /rest/v1/users/me
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "displayName": "Jane Doe",
  "preferredLocale": "lt"
}
jsonResponse · 200
{
  "id": "abc123def456",
  "email": "user@example.com",
  "displayName": "John Doe",
  "avatarUrl": "https://storage.example.com/avatars/abc123.webp",
  "preferredLocale": "lt",
  "createdAt": "2026-04-07T12:34:56.789012Z",
  "updatedAt": "2026-04-07T12:34:56.789012Z"
}
write#
PUT/rest/v1/users/me/avatarauthenticatedUpload user avatar

Uploads or replaces the avatar image for the authenticated user. Send as multipart/form-data with an "avatar" field.

Requires

authenticated

Request body · multipart/form-data

  • avatarstring · binaryrequiredAvatar image file (JPEG, PNG, or WebP)

Response · 200

  • idstringUser ID (marketplace user id — the `uid` token claim, falling back to the Keycloak `sub`)
  • emailstringUser email address
  • displayNamestringDisplay name
  • avatarUrlstringFull public URL of the user avatar
  • preferredLocalestringThe language the user is written to in; null when it was never captured (set at registration or by `PATCH /rest/v1/users/me`).One of: en · lt · lv · et
  • createdAtstring · date-timeAccount creation timestamp (ISO 8601)
  • updatedAtstring · date-timeLast update timestamp (ISO 8601)

Errors

400 · 401 · 403 · 422 · 500 — See the error reference

httpRequest
PUT /rest/v1/users/me/avatar
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "abc123def456",
  "email": "user@example.com",
  "displayName": "John Doe",
  "avatarUrl": "https://storage.example.com/avatars/abc123.webp",
  "preferredLocale": "lt",
  "createdAt": "2026-04-07T12:34:56.789012Z",
  "updatedAt": "2026-04-07T12:34:56.789012Z"
}
write#
DELETE/rest/v1/users/me/avatarauthenticatedDelete user avatar

Deletes the avatar image for the authenticated user.

Requires

authenticated

Response · 204

No content.

Errors

401 · 403 · 500 — See the error reference

httpRequest
DELETE /rest/v1/users/me/avatar
Authorization: Bearer $TOKEN
write#

Team & Access 18 operations

GET/rest/v1/seller/access/membersadministratorList team members

Lists the authenticated administrator's team members (excluding removed seats), ordered by join date. The team is a bounded set (the account owner's seat plus invited members), so the response is the full membership list — no cursor…

Requires

administrator

Response · 200

  • itemsarray<object>required
    • membershipIdstring · uuidrequired
    • userIdstringrequiredThe member's platform user id — pass as `?actorId=` to `GET /rest/v1/seller/accounts/{accountId}/activity` (Chronicle) to see this member's activity.
    • namestringMember display-name snapshot
    • emailstring · emailrequired
    • roleobjectrequired
    • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • statusstringrequiredOne of: active · suspended · removed
    • isSelfbooleanrequiredThe member is the requester.
    • isLastAdministratorbooleanrequiredThe sole active seat whose role grants team & payouts.
    • joinedAtstring · date-timerequired
    • suspendedAtstring · date-time

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/access/members
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "membershipId": "01932a00-0000-7000-8000-000000000001",
      "userId": "01932a00-0000-7000-8000-0000000000aa",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "role": {
        "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
        "name": "Manager",
        "type": "preset",
        "createdFromPreset": "manager"
      },
      "capabilities": {
        "products": "read_write",
        "orders": "read",
        "stock": "read_write",
        "pricing": "none",
        "promotions": "none",
        "activity": "read"
      },
      "scope": {
        "type": "whole_account",
        "storeIds": []
      },
      "status": "active",
      "isSelf": false,
      "isLastAdministrator": false,
      "joinedAt": "2026-05-19T10:30:00.000000Z",
      "suspendedAt": null
    }
  ]
}
read#
GET/rest/v1/seller/access/members/{membershipId}administratorGet team member

Returns a single team member of the authenticated administrator's account. Restricted to the account owner or a member holding the Administrator role (the “Team & payouts” privilege); other members receive 403 `/errors/forbidden`.

Requires

administrator

Path parameters

  • membershipIdstring · uuidrequired

Response · 200

  • membershipIdstring · uuidrequired
  • userIdstringrequiredThe member's platform user id — pass as `?actorId=` to `GET /rest/v1/seller/accounts/{accountId}/activity` (Chronicle) to see this member's activity.
  • namestringMember display-name snapshot
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
    • createdFromPresetstringOne of: administrator · manager · support · catalog · null
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredOne of: active · suspended · removed
  • isSelfbooleanrequiredThe member is the requester.
  • isLastAdministratorbooleanrequiredThe sole active seat whose role grants team & payouts.
  • joinedAtstring · date-timerequired
  • suspendedAtstring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/access/members/01914d0e-5e6f-7071-8283-9e0f10213245
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "membershipId": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-0000000000aa",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": {
    "id": "01914d0e-92a3-74b5-86c7-324354657689",
    "name": "Manager",
    "type": "preset",
    "createdFromPreset": "manager"
  },
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "active",
  "isSelf": false,
  "isLastAdministrator": false,
  "joinedAt": "2026-05-19T10:30:00.000000Z",
  "suspendedAt": null
}
read#
POST/rest/v1/seller/access/members/{membershipId}/suspendadministratorSuspend team member

Suspends an active team member. Rejected with `422 /errors/invalid-state` when the member is the account's sole active Administrator or is not currently active. The optional `reason` is a free-text note (max 500 chars) — an absent or blank…

Requires

administrator

Path parameters

  • membershipIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 200

  • membershipIdstring · uuidrequired
  • userIdstringrequiredThe member's platform user id — pass as `?actorId=` to `GET /rest/v1/seller/accounts/{accountId}/activity` (Chronicle) to see this member's activity.
  • namestringMember display-name snapshot
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
    • createdFromPresetstringOne of: administrator · manager · support · catalog · null
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredOne of: active · suspended · removed
  • isSelfbooleanrequiredThe member is the requester.
  • isLastAdministratorbooleanrequiredThe sole active seat whose role grants team & payouts.
  • joinedAtstring · date-timerequired
  • suspendedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/members/01914d0e-a3b4-75c6-97d8-43546576879a/suspend
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": "On leave until August"
}
jsonResponse · 200
{
  "membershipId": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-0000000000aa",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": {
    "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "name": "Manager",
    "type": "preset",
    "createdFromPreset": "manager"
  },
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "active",
  "isSelf": false,
  "isLastAdministrator": false,
  "joinedAt": "2026-05-19T10:30:00.000000Z",
  "suspendedAt": null
}
write#
POST/rest/v1/seller/access/members/{membershipId}/restoreadministratorRestore team member

Restores a suspended team member to active. Rejected with `422 /errors/invalid-state` when the member is not currently suspended. Returns the refreshed member. Restricted to the account owner or a member holding the Administrator role (the…

Requires

administrator

Path parameters

  • membershipIdstring · uuidrequired

Response · 200

  • membershipIdstring · uuidrequired
  • userIdstringrequiredThe member's platform user id — pass as `?actorId=` to `GET /rest/v1/seller/accounts/{accountId}/activity` (Chronicle) to see this member's activity.
  • namestringMember display-name snapshot
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
    • createdFromPresetstringOne of: administrator · manager · support · catalog · null
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredOne of: active · suspended · removed
  • isSelfbooleanrequiredThe member is the requester.
  • isLastAdministratorbooleanrequiredThe sole active seat whose role grants team & payouts.
  • joinedAtstring · date-timerequired
  • suspendedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/members/01914d0e-c5d6-77e8-b9fa-6576879aabbc/restore
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "membershipId": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-0000000000aa",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": {
    "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
    "name": "Manager",
    "type": "preset",
    "createdFromPreset": "manager"
  },
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "active",
  "isSelf": false,
  "isLastAdministrator": false,
  "joinedAt": "2026-05-19T10:30:00.000000Z",
  "suspendedAt": null
}
write#
POST/rest/v1/seller/access/members/{membershipId}/removeadministratorRemove team member

Removes a team member — terminal, soft-removed (the row is retained with status `removed` so the audit trail survives and the seat can be re-invited). Rejected with `422 /errors/invalid-state` when the member is the account's sole active…

Requires

administrator

Path parameters

  • membershipIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 200

  • membershipIdstring · uuidrequired
  • userIdstringrequiredThe member's platform user id — pass as `?actorId=` to `GET /rest/v1/seller/accounts/{accountId}/activity` (Chronicle) to see this member's activity.
  • namestringMember display-name snapshot
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
    • createdFromPresetstringOne of: administrator · manager · support · catalog · null
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredOne of: active · suspended · removed
  • isSelfbooleanrequiredThe member is the requester.
  • isLastAdministratorbooleanrequiredThe sole active seat whose role grants team & payouts.
  • joinedAtstring · date-timerequired
  • suspendedAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/members/01914d0e-6f70-7182-9394-0f1021324356/remove
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": "On leave until August"
}
jsonResponse · 200
{
  "membershipId": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-0000000000aa",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": {
    "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
    "name": "Manager",
    "type": "preset",
    "createdFromPreset": "manager"
  },
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "active",
  "isSelf": false,
  "isLastAdministrator": false,
  "joinedAt": "2026-05-19T10:30:00.000000Z",
  "suspendedAt": null
}
write#
POST/rest/v1/seller/access/members/{membershipId}/roleadministratorChange team member role

Grants a live account role to a team member. Rejected with `422 /errors/invalid-state` when it would demote the account's sole active Administrator. An unknown or archived role returns `404`. Returns the refreshed member. Restricted to the…

Requires

administrator

Path parameters

  • membershipIdstring · uuidrequired

Request body · application/json

  • roleIdstring · uuidrequiredThe id of the live account role to grant the member.

Response · 200

  • membershipIdstring · uuidrequired
  • userIdstringrequiredThe member's platform user id — pass as `?actorId=` to `GET /rest/v1/seller/accounts/{accountId}/activity` (Chronicle) to see this member's activity.
  • namestringMember display-name snapshot
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
    • createdFromPresetstringOne of: administrator · manager · support · catalog · null
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredOne of: active · suspended · removed
  • isSelfbooleanrequiredThe member is the requester.
  • isLastAdministratorbooleanrequiredThe sole active seat whose role grants team & payouts.
  • joinedAtstring · date-timerequired
  • suspendedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/members/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/role
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "roleId": "01932a00-0000-7000-8000-000000000001"
}
jsonResponse · 200
{
  "membershipId": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-0000000000aa",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": {
    "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
    "name": "Manager",
    "type": "preset",
    "createdFromPreset": "manager"
  },
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "active",
  "isSelf": false,
  "isLastAdministrator": false,
  "joinedAt": "2026-05-19T10:30:00.000000Z",
  "suspendedAt": null
}
write#
POST/rest/v1/seller/access/members/{membershipId}/store-scopeadministratorChange team member store scope

Changes which stores a team member covers. A `selected_stores` scope must reference at least one account-owned store; an empty selection or a store the account does not own returns `422 /errors/invalid-state`. A `whole_account` scope…

Requires

administrator

Path parameters

  • membershipIdstring · uuidrequired

Request body · application/json

  • scopeTypestringrequiredOne of: whole_account · selected_stores
  • storeIdsarray<string>Required (non-empty) for `selected_stores`; ignored for `whole_account`.

Response · 200

  • membershipIdstring · uuidrequired
  • userIdstringrequiredThe member's platform user id — pass as `?actorId=` to `GET /rest/v1/seller/accounts/{accountId}/activity` (Chronicle) to see this member's activity.
  • namestringMember display-name snapshot
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
    • createdFromPresetstringOne of: administrator · manager · support · catalog · null
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredOne of: active · suspended · removed
  • isSelfbooleanrequiredThe member is the requester.
  • isLastAdministratorbooleanrequiredThe sole active seat whose role grants team & payouts.
  • joinedAtstring · date-timerequired
  • suspendedAtstring · date-time

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/members/01914d0e-6f70-7182-9394-0f1021324356/store-scope
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "scopeType": "selected_stores",
  "storeIds": [
    "01932a00-0000-7000-8000-000000000010"
  ]
}
jsonResponse · 200
{
  "membershipId": "01932a00-0000-7000-8000-000000000001",
  "userId": "01932a00-0000-7000-8000-0000000000aa",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": {
    "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "name": "Manager",
    "type": "preset",
    "createdFromPreset": "manager"
  },
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "active",
  "isSelf": false,
  "isLastAdministrator": false,
  "joinedAt": "2026-05-19T10:30:00.000000Z",
  "suspendedAt": null
}
write#
GET/rest/v1/seller/access/rolesadministratorList access roles

Lists the account's live roles for the Roles tab — the four presets first, then custom roles; archived roles are excluded. Administrator-only. The four presets are materialized per account on first access to any Team & access endpoint…

Requires

administrator

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequired
    • typestringrequiredOne of: preset · custom
    • namestringrequired
    • descriptionstringrequired
    • createdFromPresetstringFor a preset role, the preset it represents. For a custom role, the preset it was seeded from in the role editor (via the create payload's `createdFromPreset`), or null when authored from scratch.One of: administrator · manager · support · catalog · null
    • grantsTeamAndPayoutsbooleanrequiredTrue only for the Administrator preset — drives administrator-only hub access and the last-administrator guard. Custom roles never grant team & payouts.
    • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • holderCountintegerrequiredNumber of members holding the role who have not been removed — suspended members still hold their role.
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/access/roles
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01961f5e-9a3b-7c40-b8e6-0000000000c1",
      "type": "custom",
      "name": "Fulfilment lead",
      "description": "Runs the warehouse desk",
      "createdFromPreset": null,
      "grantsTeamAndPayouts": false,
      "capabilities": {
        "products": "read_write",
        "orders": "read",
        "stock": "read_write",
        "pricing": "none",
        "promotions": "none",
        "activity": "read"
      },
      "holderCount": 3,
      "createdAt": "2026-08-06T12:34:56.789012Z",
      "updatedAt": "2026-08-06T12:34:56.789012Z"
    }
  ]
}
read#
POST/rest/v1/seller/access/rolesadministratorCreate access role

Creates a seller-authored custom role from the role editor. The name must be unique among live roles (case-insensitive) — a duplicate returns `409`. At least one capability area must be granted — an all-`none` matrix returns `422…

Requires

administrator

Request body · application/json

  • namestringrequiredRole name — unique among live roles, case-insensitive.
  • capabilitiesobjectrequiredFull capability matrix — at least one area must be granted (an all-`none` matrix is rejected with 422).
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • descriptionstringOptional role description.
  • createdFromPresetstringOptional — records which preset this custom role was seeded from in the role editor. Omit or send null for a role authored from scratch. An unknown value is rejected with 422 /errors/validation-failed. When supplied, the created role…One of: administrator · manager · support · catalog · null

Response · 201

  • idstring · uuidrequired
  • typestringrequiredOne of: preset · custom
  • namestringrequired
  • descriptionstringrequired
  • createdFromPresetstringFor a preset role, the preset it represents. For a custom role, the preset it was seeded from in the role editor (via the create payload's `createdFromPreset`), or null when authored from scratch.One of: administrator · manager · support · catalog · null
  • grantsTeamAndPayoutsbooleanrequiredTrue only for the Administrator preset — drives administrator-only hub access and the last-administrator guard. Custom roles never grant team & payouts.
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • holderCountintegerrequiredNumber of members holding the role who have not been removed — suspended members still hold their role.
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/roles
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Fulfilment lead",
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "description": "Runs the warehouse desk",
  "createdFromPreset": "catalog"
}
jsonResponse · 201
{
  "id": "01961f5e-9a3b-7c40-b8e6-0000000000c1",
  "type": "custom",
  "name": "Fulfilment lead",
  "description": "Runs the warehouse desk",
  "createdFromPreset": null,
  "grantsTeamAndPayouts": false,
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "holderCount": 3,
  "createdAt": "2026-08-06T12:34:56.789012Z",
  "updatedAt": "2026-08-06T12:34:56.789012Z"
}
write#
GET/rest/v1/seller/access/roles/{roleId}administratorGet access role

Reads a single role with its holders — members holding the role who have not been removed (suspended members still hold their role) — for the role lifecycle screen. Administrator-only. Restricted to the account owner or a member holding…

Requires

administrator

Path parameters

  • roleIdstring · uuidrequired

Response · 200

  • idstring · uuidrequired
  • typestringrequiredOne of: preset · custom
  • namestringrequired
  • descriptionstringrequired
  • createdFromPresetstringFor a preset role, the preset it represents. For a custom role, the preset it was seeded from in the role editor (via the create payload's `createdFromPreset`), or null when authored from scratch.One of: administrator · manager · support · catalog · null
  • grantsTeamAndPayoutsbooleanrequiredTrue only for the Administrator preset — drives administrator-only hub access and the last-administrator guard. Custom roles never grant team & payouts.
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • holderCountintegerrequiredNumber of members holding the role who have not been removed — suspended members still hold their role.
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired
  • holdersarray<object>required
    • membershipIdstring · uuidrequired
    • namestring
    • emailstring · emailrequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/access/roles/01914d0e-b4c5-76d7-a8e9-546576879aab
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01961f5e-9a3b-7c40-b8e6-0000000000c1",
  "type": "custom",
  "name": "Fulfilment lead",
  "description": "Runs the warehouse desk",
  "createdFromPreset": null,
  "grantsTeamAndPayouts": false,
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "holderCount": 3,
  "createdAt": "2026-08-06T12:34:56.789012Z",
  "updatedAt": "2026-08-06T12:34:56.789012Z",
  "holders": [
    {
      "membershipId": "01961f5e-9a3b-7c40-b8e6-0000000000d1",
      "name": "Rasa Petraitiene",
      "email": "rasa@store.example"
    }
  ]
}
read#
POST/rest/v1/seller/access/roles/{roleId}/reviseadministratorRevise access role

Revises a custom role — its name, description, and capability matrix ("Save changes"). Preset roles are immutable and return `422 /errors/invalid-state`. A name colliding with another live role returns `409`. Administrator-only. Restricted…

Requires

administrator

Path parameters

  • roleIdstring · uuidrequired

Request body · application/json

  • namestringrequiredRole name — unique among live roles, case-insensitive.
  • capabilitiesobjectrequiredFull capability matrix — at least one area must be granted (an all-`none` matrix is rejected with 422).
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • descriptionstringOptional role description.

Response · 200

  • idstring · uuidrequired
  • typestringrequiredOne of: preset · custom
  • namestringrequired
  • descriptionstringrequired
  • createdFromPresetstringFor a preset role, the preset it represents. For a custom role, the preset it was seeded from in the role editor (via the create payload's `createdFromPreset`), or null when authored from scratch.One of: administrator · manager · support · catalog · null
  • grantsTeamAndPayoutsbooleanrequiredTrue only for the Administrator preset — drives administrator-only hub access and the last-administrator guard. Custom roles never grant team & payouts.
  • capabilitiesobjectrequiredGrant level per capability area, resolved from the role. Every one of the six areas is always present. The five write areas (`products`, `orders`, `stock`, `pricing`, `promotions`) hold `none` · `read` · `read_write`. `activity` is…
    • productsstringrequiredOne of: none · read · read_write
    • ordersstringrequiredOne of: none · read · read_write
    • stockstringrequiredOne of: none · read · read_write
    • pricingstringrequiredOne of: none · read · read_write
    • promotionsstringrequiredOne of: none · read · read_write
    • activitystringrequiredRead-only capability — grants visibility of the account's activity feed. `read_write` is invalid.One of: none · read
  • holderCountintegerrequiredNumber of members holding the role who have not been removed — suspended members still hold their role.
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/roles/01914d0e-8192-73a4-b5b6-213243546578/revise
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Fulfilment lead",
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "description": "Runs the warehouse desk"
}
jsonResponse · 200
{
  "id": "01961f5e-9a3b-7c40-b8e6-0000000000c1",
  "type": "custom",
  "name": "Fulfilment lead",
  "description": "Runs the warehouse desk",
  "createdFromPreset": null,
  "grantsTeamAndPayouts": false,
  "capabilities": {
    "products": "read_write",
    "orders": "read",
    "stock": "read_write",
    "pricing": "none",
    "promotions": "none",
    "activity": "read"
  },
  "holderCount": 3,
  "createdAt": "2026-08-06T12:34:56.789012Z",
  "updatedAt": "2026-08-06T12:34:56.789012Z"
}
write#
POST/rest/v1/seller/access/roles/{roleId}/archiveadministratorArchive access role

Archives a custom role, atomically re-roling every holder onto a chosen live role. The `reassignments` list must cover every holder of the role who has not been removed (active and suspended); a suspended holder is re-roled and stays…

Requires

administrator

Path parameters

  • roleIdstring · uuidrequired

Request body · application/json

  • reassignmentsarray<object>requiredMust cover every holder of the role being archived who has not been removed (active and suspended); a suspended holder is re-roled and stays suspended.
    • membershipIdstringrequiredMembership currently holding the role being archived.
    • newRoleIdstringrequiredLive role the holder is reassigned to.

Response · 204

No content.

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/roles/01914d0e-6f70-7182-9394-0f1021324356/archive
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reassignments": [
    {
      "membershipId": "01961f5e-9a3b-7c40-b8e6-0000000000d1",
      "newRoleId": "01961f5e-9a3b-7c40-b8e6-0000000000c3"
    }
  ]
}
write#
GET/rest/v1/seller/access/invitationsadministratorList invitations

Lists the account's invitations, newest first. Administrator-only. `status` is the effective (expiry-on-read) status — a stored `pending` invitation past its expiry reads as `expired` without a background writer. Restricted to the account…

Requires

administrator

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequired
    • emailstring · emailrequired
    • roleobjectrequired
    • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • statusstringrequiredEffective (expiry-on-read) status.One of: pending · accepted · expired · revoked
    • sentAtstring · date-timerequired
    • expiresAtstring · date-timerequired7 days after the invitation was sent or last resent.
    • resentAtstring · date-time

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/access/invitations
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01961f5e-9a3b-7c40-b8e6-000000000201",
      "email": "invitee@example.com",
      "role": {
        "id": "01961f5e-9a3b-7c40-b8e6-000000000031",
        "name": "Manager",
        "type": "preset"
      },
      "scope": {
        "type": "whole_account",
        "storeIds": []
      },
      "status": "pending",
      "sentAt": "2026-08-06T10:30:00.000000Z",
      "expiresAt": "2026-08-13T10:30:00.000000Z",
      "resentAt": null
    }
  ]
}
read#
POST/rest/v1/seller/access/invitationsadministratorInvite a member

Invites a person by email to a live role, scoped to the whole account or selected stores. Sends a one-time accept-link email that expires after 7 days. Administrator-only. A pending invitation already outstanding for the same email, or an…

Requires

administrator

Request body · application/json

  • emailstring · emailrequired
  • roleIdstring · uuidrequiredThe live role to grant on acceptance.
  • scopeobjectStore scope for the seat. Defaults to `whole_account` when omitted. `storeIds` is required (non-empty) for `selected_stores` and ignored for `whole_account`.
    • typestringOne of: whole_account · selected_stores
    • storeIdsarray<string>

Response · 201

  • idstring · uuidrequired
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredEffective (expiry-on-read) status.One of: pending · accepted · expired · revoked
  • sentAtstring · date-timerequired
  • expiresAtstring · date-timerequired7 days after the invitation was sent or last resent.
  • resentAtstring · date-time

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/invitations
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "email": "invitee@example.com",
  "roleId": "01961f5e-9a3b-7c40-b8e6-000000000031",
  "scope": {
    "type": "whole_account",
    "storeIds": []
  }
}
jsonResponse · 201
{
  "id": "01961f5e-9a3b-7c40-b8e6-000000000201",
  "email": "invitee@example.com",
  "role": {
    "id": "01961f5e-9a3b-7c40-b8e6-000000000031",
    "name": "Manager",
    "type": "preset"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "pending",
  "sentAt": "2026-08-06T10:30:00.000000Z",
  "expiresAt": "2026-08-13T10:30:00.000000Z",
  "resentAt": null
}
write#
POST/rest/v1/seller/access/invitations/{invitationId}/resendadministratorResend an invitation

Regenerates the accept token, resets the 7-day expiry, and re-sends the email. Allowed while the invitation is pending (including pending-past-expiry); an accepted or revoked invitation returns `422 /errors/invalid-state`. An invitation is…

Requires

administrator

Path parameters

  • invitationIdstring · uuidrequired

Response · 200

  • idstring · uuidrequired
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredEffective (expiry-on-read) status.One of: pending · accepted · expired · revoked
  • sentAtstring · date-timerequired
  • expiresAtstring · date-timerequired7 days after the invitation was sent or last resent.
  • resentAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/invitations/01914d0e-4d5e-7f60-b172-8d9e0f102134/resend
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01961f5e-9a3b-7c40-b8e6-000000000201",
  "email": "invitee@example.com",
  "role": {
    "id": "01961f5e-9a3b-7c40-b8e6-000000000031",
    "name": "Manager",
    "type": "preset"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "pending",
  "sentAt": "2026-08-06T10:30:00.000000Z",
  "expiresAt": "2026-08-13T10:30:00.000000Z",
  "resentAt": null
}
write#
POST/rest/v1/seller/access/invitations/{invitationId}/revokeadministratorRevoke an invitation

Revokes a pending invitation so its accept link can no longer be used. A non-pending invitation returns `422 /errors/invalid-state`. Administrator-only. Restricted to the account owner or a member holding the Administrator role (the “Team…

Requires

administrator

Path parameters

  • invitationIdstring · uuidrequired

Response · 200

  • idstring · uuidrequired
  • emailstring · emailrequired
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
    • typestringrequiredOne of: preset · custom
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredEffective (expiry-on-read) status.One of: pending · accepted · expired · revoked
  • sentAtstring · date-timerequired
  • expiresAtstring · date-timerequired7 days after the invitation was sent or last resent.
  • resentAtstring · date-time

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/access/invitations/01914d0e-92a3-74b5-86c7-324354657689/revoke
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01961f5e-9a3b-7c40-b8e6-000000000201",
  "email": "invitee@example.com",
  "role": {
    "id": "01961f5e-9a3b-7c40-b8e6-000000000031",
    "name": "Manager",
    "type": "preset"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "pending",
  "sentAt": "2026-08-06T10:30:00.000000Z",
  "expiresAt": "2026-08-13T10:30:00.000000Z",
  "resentAt": null
}
write#
POST/rest/v1/access/invitations/lookuppublicLook up an invitation by token

Resolves an invitation by its accept-link token for the accept landing page. No authentication. The token goes in the request body — never in the URL — so it is not written to any access log on the way in; the invitation link carries it in…

Requires

public

Request body · application/json

  • tokenstringrequiredThe token from the invitation link (the `token` in its URL fragment). Any value that is not a live token gets the same bare 404.

Response · 200

  • accountNamestringrequired
  • inviterNamestringrequired
  • roleNamestringrequired
  • statusstringrequiredOne of: pending · accepted · expired · revoked
  • emailstring · emailrequired

Errors

400 · 404 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/access/invitations/lookup
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "token": "3f0c9a1e5b7d2c4e6a8b0d1f3e5c7a9b1d3f5e7c9a0b2d4f6e8a1c3e5b7d9f0a"
}
jsonResponse · 200
{
  "accountName": "Acme Store",
  "inviterName": "Acme Store",
  "roleName": "Manager",
  "status": "pending",
  "email": "invitee@example.com"
}
write#
POST/rest/v1/access/invitations/acceptauthenticatedAccept an invitation

Accepts a pending invitation, creating a membership in the inviting account. Only the person the invitation was sent to may accept it: the signed-in marketplace-realm user's address must be the invited address, compared case-insensitively…

Requires

authenticated

Request body · application/json

  • tokenstringrequiredThe token from the invitation link (the `token` in its URL fragment).

Response · 201

  • membershipIdstring · uuidrequired
  • accountUserIdstringrequiredThe inviting account's user id — the account the seat belongs to.
  • roleobjectrequired
    • idstring · uuidrequired
    • namestringrequired
  • scopeobjectrequiredWhether a membership or invitation applies to the whole account or a selected set of stores.
    • typestringrequiredOne of: whole_account · selected_stores
    • storeIdsarray<string>requiredPopulated only for `selected_stores`; empty for `whole_account`.
  • statusstringrequiredOne of: active · suspended · removed
  • joinedAtstring · date-timerequired

Errors

400 · 401 · 403 · 404 · 409 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/access/invitations/accept
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "token": "Token"
}
jsonResponse · 201
{
  "membershipId": "01961f5e-9a3b-7c40-b8e6-000000000401",
  "accountUserId": "uid-account-1",
  "role": {
    "id": "01961f5e-9a3b-7c40-b8e6-000000000031",
    "name": "Manager"
  },
  "scope": {
    "type": "whole_account",
    "storeIds": []
  },
  "status": "active",
  "joinedAt": "2026-08-06T10:35:00.000000Z"
}
write#

Agent Connect 2 operations

POST/rest/v1/auth/agents/registerpublicRegister an agent connection

Registers an agent connection request (mediated RFC 7591 DCR). Returns a reserved agt_ client id, a user_code to approve, and a poll URL. Idempotency-Key replays the same request.

Requires

public

Request body · application/json

  • client_namestringrequiredHuman-readable agent name (RFC 7591 client_name)
  • scopestringrequiredSpace-delimited requested capability manifest — "area:level" tokens
  • surfacestringrequiredWhich surface the agent servesOne of: seller · buyer
  • connect_methodstringrequiredHow the agent connects (self_connect | pairing)One of: self_connect · pairing
  • redirect_urisarray<string>Informational: where the assistant returns after approval (RFC 7591 redirect_uris). Not used for the Keycloak client — every agent client is headless.
  • token_endpoint_auth_methodstringRFC 7591 token_endpoint_auth_method (advisory)
  • grant_typesarray<string>RFC 7591 grant_types (advisory)
  • software_idstringSoftware identifier of the agent build (RFC 7591 software_id) — surfaced as its provider
  • software_statementstringRFC 7591 software_statement (signed assertion)

Response · 201

  • request_idstring · uuidrequired
  • client_idstringrequiredThe reserved agt_ client id.
  • statusstringrequiredOne of: pending
  • user_codestringrequiredThe code the human enters to approve the connection.
  • verification_uristring · urirequired
  • verification_uri_completestring · urirequiredThe verification URI with the user code pre-filled.
  • expires_inintegerrequiredSeconds until the connection request expires.
  • intervalintegerrequiredMinimum seconds to wait between polls.
  • pollstringrequiredThe path to poll for approval and the one-time credential.

Errors

400 · 409 · 422 · 429 · 500 — See the error reference

httpRequest
POST /rest/v1/auth/agents/register
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "client_name": "Acme Ops Bot",
  "scope": "products:read_write orders:read",
  "surface": "seller",
  "connect_method": "self_connect",
  "redirect_uris": [],
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": [],
  "software_id": "acme/ops",
  "software_statement": null
}
jsonResponse · 201
{
  "request_id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
  "client_id": "Client id",
  "status": "pending",
  "user_code": "User code",
  "verification_uri": "https://api.example.com",
  "verification_uri_complete": "https://api.example.com",
  "expires_in": 0,
  "interval": 0,
  "poll": "Poll"
}
write#
GET/rest/v1/auth/agents/requests/{request_id}publicPoll an agent connection request

Polls a connection request by its opaque id. Returns status (pending_approval | approved | declined | expired); the credential is delivered once on the first poll after approval.

Requires

public

Path parameters

  • request_idstringrequiredOpaque connection-request id (the poll bearer)

Response · 200

  • statusstringrequiredOne of: pending · approved · declined · expired
  • expires_atstring · date-timeOmitted once the request is no longer awaiting approval.
  • credentialobjectThe one-time client credential. Present on the first poll after approval and never again.

Errors

404 · 500 — See the error reference

httpRequest
GET /rest/v1/auth/agents/requests/Request id
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "status": "pending",
  "expires_at": "2026-09-10T09:24:11Z",
  "credential": {}
}
read#

Agents 16 operations

GET/rest/v1/seller/agentsadministratorList seller agents

Cursor-paginated roster of the authenticated administrator's seller agents, newest first.

Requires

administrator

Query parameters

  • afterstring · uuidReturn items after this UUID (forward pagination)
  • beforestring · uuidReturn items before this UUID (backward pagination)
  • limitintegerMaximum number of results per page (max 100)
  • includeTotalCountbooleanInclude total count in response metadata (expensive)

Response · 200

  • itemsarray<object>
    • idstringrequired
    • clientIdstringrequired
    • namestringrequired
    • providerstring
    • surfacestringrequired
    • connectionMethodstringrequired
    • truststringrequired
    • statusstringrequired
    • scopeTypestringrequired
    • actorIdstringrequired
    • connectedAtstring
    • createdAtstringrequired
    • lastActiveAtstring
    • effectiveobjectrequired
    • orphanedbooleanrequired
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerPresent only when includeTotalCount=true.

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/agents
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "Id",
      "clientId": "Client id",
      "name": "Name",
      "provider": "Provider",
      "surface": "Surface",
      "connectionMethod": "Connection method",
      "trust": "Trust",
      "status": "Status",
      "scopeType": "Scope type",
      "actorId": "Actor id",
      "connectedAt": "Connected at",
      "createdAt": "Created at",
      "lastActiveAt": "Last active at",
      "effective": {},
      "orphaned": false
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "prevCursor": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "totalCount": 129900
  }
}
read#
POST/rest/v1/seller/agentsadministratorCreate seller service agent

Connects a headless seller service agent (born active) and provisions its Keycloak client. The one-time secret is in the response credential.

Requires

administrator

Request body · application/json

  • namestring
  • providerstring
  • capabilitiesobject
  • scopeTypestringOne of: whole_account · selected_stores
  • storeIdsarray<string>

Response · 201

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Ops Bot",
  "provider": "acme/ops",
  "capabilities": {
    "products": "read_write",
    "orders": "read"
  },
  "scopeType": "whole_account",
  "storeIds": []
}
jsonResponse · 201
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#
GET/rest/v1/seller/agents/requestsadministratorList agent access requests

Cursor-paginated approval inbox of the authenticated administrator (pending; those past TTL surface as expired).

Requires

administrator

Query parameters

  • afterstring · uuidReturn items after this UUID (forward pagination)
  • beforestring · uuidReturn items before this UUID (backward pagination)
  • limitintegerMaximum number of results per page (max 100)
  • includeTotalCountbooleanInclude total count in response metadata (expensive)

Response · 200

  • itemsarray<object>
    • idstringrequired
    • surfacestringrequired
    • connectionMethodstringrequired
    • namestringrequired
    • providerstring
    • truststringrequired
    • requestedCapabilitiesobjectrequired
    • statusstringrequired
    • userCodestringrequired
    • reservedClientIdstringrequired
    • expiresAtstringrequired
    • createdAtstringrequired
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerPresent only when includeTotalCount=true.

Errors

401 · 403 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/agents/requests
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "Id",
      "surface": "Surface",
      "connectionMethod": "Connection method",
      "name": "Name",
      "provider": "Provider",
      "trust": "Trust",
      "requestedCapabilities": {},
      "status": "Status",
      "userCode": "User code",
      "reservedClientId": "Reserved client id",
      "expiresAt": "Expires at",
      "createdAt": "Created at"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-a3b4-75c6-97d8-43546576879a",
    "prevCursor": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
    "totalCount": 129900
  }
}
read#
POST/rest/v1/seller/accounts/{accountId}/agents/requests/redeemadministratorRedeem agent user code

Redeems a user code: claims the resolved pending request for the account named in the path and returns it for review. The caller must be able to act for that account as an Administrator — a non-member gets 404 (anti-enumeration), a known…

Requires

administrator

Path parameters

  • accountIdstringrequiredThe account (owner UserId) the code is redeemed for.

Request body · application/json

  • userCodestring

Response · 200

  • idstringrequired
  • surfacestringrequired
  • connectionMethodstringrequired
  • namestringrequired
  • providerstring
  • truststringrequired
  • requestedCapabilitiesobjectrequired
  • statusstringrequired
  • userCodestringrequired
  • reservedClientIdstringrequired
  • expiresAtstringrequired
  • createdAtstringrequired

Errors

400 · 401 · 403 · 404 · 409 · 422 · 429 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/accounts/Account id/agents/requests/redeem
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "userCode": "HXK-4PT"
}
jsonResponse · 200
{
  "id": "Id",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "name": "Name",
  "provider": "Provider",
  "trust": "Trust",
  "requestedCapabilities": {},
  "status": "Status",
  "userCode": "User code",
  "reservedClientId": "Reserved client id",
  "expiresAt": "Expires at",
  "createdAt": "Created at"
}
write#
GET/rest/v1/seller/agents/requests/{requestId}administratorGet agent access request

Returns one access request for review — identity, trust, the locked requested manifest, and the user code.

Requires

administrator

Path parameters

  • requestIdstring · uuidrequired

Response · 200

  • idstringrequired
  • surfacestringrequired
  • connectionMethodstringrequired
  • namestringrequired
  • providerstring
  • truststringrequired
  • requestedCapabilitiesobjectrequired
  • statusstringrequired
  • userCodestringrequired
  • reservedClientIdstringrequired
  • expiresAtstringrequired
  • createdAtstringrequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/agents/requests/01914d0e-8192-73a4-b5b6-213243546578
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "name": "Name",
  "provider": "Provider",
  "trust": "Trust",
  "requestedCapabilities": {},
  "status": "Status",
  "userCode": "User code",
  "reservedClientId": "Reserved client id",
  "expiresAt": "Expires at",
  "createdAt": "Created at"
}
read#
POST/rest/v1/seller/agents/requests/{requestId}/approveadministratorApprove agent access request

Approves a request: spawns the agent under the reserved client id, grants the chosen capabilities (⊆ requested), and provisions the Keycloak client. The secret is delivered to the app via its own poll, never here.

Requires

administrator

Path parameters

  • requestIdstring · uuidrequired

Request body · application/json

  • capabilitiesobject
  • scopeTypestringOne of: whole_account · selected_stores
  • storeIdsarray<string>

Response · 201

  • agentIdstringrequired

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/requests/01914d0e-6f70-7182-9394-0f1021324356/approve
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "capabilities": {
    "products": "read"
  },
  "scopeType": "whole_account",
  "storeIds": []
}
jsonResponse · 201
{
  "agentId": "Agent id"
}
write#
POST/rest/v1/seller/agents/requests/{requestId}/declineadministratorDecline agent access request

Declines a pending request. Only a pending, unexpired request can be declined (422 otherwise).

Requires

administrator

Path parameters

  • requestIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/requests/01914d0e-7081-7293-a4a5-102132435467/decline
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": "Unrecognised software"
}
write#
POST/rest/v1/seller/agents/requests/{requestId}/dismissadministratorDismiss agent access request

Dismisses a request off the inbox.

Requires

administrator

Path parameters

  • requestIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/requests/01914d0e-5e6f-7071-8283-9e0f10213245/dismiss
Authorization: Bearer $TOKEN
write#
GET/rest/v1/seller/agents/{agentId}administratorGet seller agent

Returns one seller agent's full detail, including server-computed effective access.

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/agents/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
read#
POST/rest/v1/seller/agents/{agentId}/accessadministratorChange seller agent access

Re-grants the agent's capabilities within its frozen requested ceiling. A grant beyond the request is rejected (422).

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Request body · application/json

  • capabilitiesobject

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/access
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "capabilities": {
    "products": "read"
  }
}
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#
POST/rest/v1/seller/agents/{agentId}/resumeadministratorResume seller agent

Resumes a suspended agent. Only a suspended agent can be resumed (422 otherwise).

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/01914d0e-92a3-74b5-86c7-324354657689/resume
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#
POST/rest/v1/seller/agents/{agentId}/reveal-secretadministratorReveal seller agent secret

Reveals the agent's current secret (seller-only, M1): an authenticated Keycloak pass-through read, audited via access.agent.secret_revealed. A revoked agent cannot be revealed (422).

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/01914d0e-6f70-7182-9394-0f1021324356/reveal-secret
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#
POST/rest/v1/seller/agents/{agentId}/revokeadministratorRevoke seller agent

Revokes an agent (terminal) and disables its Keycloak client. Idempotent: re-revoking returns 200.

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/revoke
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": "Rotated out of service"
}
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#
POST/rest/v1/seller/agents/{agentId}/rotate-secretadministratorRotate seller agent secret

Rotates the agent secret under the 24 h-overlap policy. The new secret is in the response credential; the previous stays valid until previousSecretExpiresAt. A revoked agent cannot rotate (422).

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/01914d0e-c5d6-77e8-b9fa-6576879aabbc/rotate-secret
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#
POST/rest/v1/seller/agents/{agentId}/store-scopeadministratorChange seller agent store scope

Changes the agent's store reach. Selected stores are S2S-verified against the account (503 on outage); the payload store ids are never trusted.

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Request body · application/json

  • scopeTypestringOne of: whole_account · selected_stores
  • storeIdsarray<string>

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/store-scope
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "scopeType": "selected_stores",
  "storeIds": []
}
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#
POST/rest/v1/seller/agents/{agentId}/suspendadministratorSuspend seller agent

Pauses an active agent. Only an active agent can be suspended (422 otherwise).

Requires

administrator

Path parameters

  • agentIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • orphanedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • storeScopeobjectrequired
    • typestringrequired
    • storeIdsarray<string>required
    • totalStoresintegerrequired
  • grantedobjectrequired
  • requestedobject
  • effectiveobjectrequired
  • credentialobjectrequired
    • clientIdstringrequired
    • secretstring
    • secretFingerprintstring
    • secretLast4string
    • createdAtstringrequired
    • lastUsedAtstring
    • rotatedAtstring
    • previousSecretExpiresAtstring
  • expiresAtstring

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/agents/01914d0e-6f70-7182-9394-0f1021324356/suspend
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": "Investigating unusual activity"
}
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "orphaned": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "storeScope": {
    "type": "Type",
    "storeIds": [
      "Store ids"
    ],
    "totalStores": 129900
  },
  "granted": {},
  "requested": {},
  "effective": {},
  "credential": {
    "clientId": "Client id",
    "secret": "Secret",
    "secretFingerprint": "Secret fingerprint",
    "secretLast4": "Secret last4",
    "createdAt": "Created at",
    "lastUsedAt": "Last used at",
    "rotatedAt": "Rotated at",
    "previousSecretExpiresAt": "Previous secret expires at"
  },
  "expiresAt": "Expires at"
}
write#

Buyer Agents 14 operations

GET/rest/v1/users/me/agentsauthenticatedList buyer agents

Lists the authenticated buyer's own agents, newest first, cursor-paginated.

Requires

authenticated

Query parameters

  • afterstringReturn items after this UUID (forward pagination)
  • beforestringReturn items before this UUID (backward pagination)
  • limitintegerMaximum number of results per page (max 100)
  • includeTotalCountbooleanInclude total count in response metadata (expensive)

Response · 200

  • itemsarray<object>
    • idstringrequired
    • clientIdstringrequired
    • namestringrequired
    • providerstring
    • connectionMethodstringrequired
    • truststringrequired
    • statusstringrequired
    • expiringbooleanrequired
    • expiredbooleanrequired
    • connectedAtstring
    • expiresAtstring
    • createdAtstring
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerPresent only when includeTotalCount=true.

Errors

401 · 403 · 500 — See the error reference

httpRequest
GET /rest/v1/users/me/agents
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "Id",
      "clientId": "Client id",
      "name": "Name",
      "provider": "Provider",
      "connectionMethod": "Connection method",
      "trust": "Trust",
      "status": "Status",
      "expiring": false,
      "expired": false,
      "connectedAt": "Connected at",
      "expiresAt": "Expires at",
      "createdAt": "Created at"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-b4c5-76d7-a8e9-546576879aab",
    "prevCursor": "01914d0e-b4c5-76d7-a8e9-546576879aab",
    "totalCount": 129900
  }
}
read#
POST/rest/v1/users/me/agentsauthenticatedCreate buyer agent

Connects a new manual buyer agent (born active) and returns its one-time client secret. A spending mandate is required when the ordering scope is read_write.

Requires

authenticated

Request body · application/json

  • namestring
  • providerstring
  • scopesobject
  • expiryDaysintegerOne of: 30 · 90 · 365
  • mandateobject
    • perOrderCapAmountintegerrequired
    • monthlyCapAmountintegerrequired
    • scaobjectrequired
    • currencystringOne of: EUR

Response · 201

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • expiringbooleanrequired
  • expiredbooleanrequired
  • neverUsedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • expiresAtstring
  • createdAtstring
  • scopesobjectrequired
  • requestedobject
  • credentialobjectrequired
  • mandateobject
  • spendobject

Errors

400 · 401 · 403 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/users/me/agents
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "name": "Weekly Grocery Bot",
  "provider": "acme/shopper",
  "scopes": {
    "browse_search": "read",
    "ordering": "read_write"
  },
  "expiryDays": 30,
  "mandate": {
    "perOrderCapAmount": 5000,
    "monthlyCapAmount": 50000,
    "sca": {
      "reference": "sca_9f2c8ab1",
      "completedAt": null
    },
    "currency": "EUR"
  }
}
jsonResponse · 201
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "expiring": false,
  "expired": false,
  "neverUsed": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "scopes": {},
  "requested": {},
  "credential": {},
  "mandate": {},
  "spend": {}
}
write#
GET/rest/v1/users/me/agents/requestsauthenticatedList buyer agent requests

Lists the authenticated buyer's app-request inbox (pending and, past their TTL, expired), cursor-paginated.

Requires

authenticated

Query parameters

  • afterstringReturn items after this UUID (forward pagination)
  • beforestringReturn items before this UUID (backward pagination)
  • limitintegerMaximum number of results per page (max 100)
  • includeTotalCountbooleanInclude total count in response metadata (expensive)

Response · 200

  • itemsarray<object>
    • idstringrequired
    • connectionMethodstringrequired
    • requestCodestringrequired
    • selfReportedNamestringrequired
    • selfReportedProviderstring
    • requestedobjectrequired
    • statusstringrequired
    • expiredbooleanrequired
    • expiresAtstring
    • createdAtstring
    • resultingAgentIdstring
  • _metadataobject
    • limitinteger
    • hasMoreboolean
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerPresent only when includeTotalCount=true.

Errors

401 · 403 · 500 — See the error reference

httpRequest
GET /rest/v1/users/me/agents/requests
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "Id",
      "connectionMethod": "Connection method",
      "requestCode": "Request code",
      "selfReportedName": "Self reported name",
      "selfReportedProvider": "Self reported provider",
      "requested": {},
      "status": "Status",
      "expired": false,
      "expiresAt": "Expires at",
      "createdAt": "Created at",
      "resultingAgentId": "Resulting agent id"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": "01914d0e-8192-73a4-b5b6-213243546578",
    "prevCursor": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "totalCount": 129900
  }
}
read#
POST/rest/v1/users/me/agents/requests/redeemauthenticatedRedeem buyer agent user code

Redeems a user code shown by a companion app that registered on the buyer surface (self_connect): claims the resolved pending app-request into the authenticated buyer's inbox and returns it in the buyer wire shape. Resolution is pinned to…

Requires

authenticated

Request body · application/json

  • userCodestring

Response · 200

  • idstringrequired
  • connectionMethodstringrequired
  • requestCodestringrequired
  • selfReportedNamestringrequired
  • selfReportedProviderstring
  • requestedobjectrequired
  • statusstringrequired
  • expiredbooleanrequired
  • expiresAtstring
  • createdAtstring
  • resultingAgentIdstring

Errors

400 · 401 · 403 · 404 · 409 · 422 · 429 · 500 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/requests/redeem
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "userCode": "7XBQ-PF95"
}
jsonResponse · 200
{
  "id": "Id",
  "connectionMethod": "Connection method",
  "requestCode": "Request code",
  "selfReportedName": "Self reported name",
  "selfReportedProvider": "Self reported provider",
  "requested": {},
  "status": "Status",
  "expired": false,
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "resultingAgentId": "Resulting agent id"
}
write#
GET/rest/v1/users/me/agents/requests/{requestId}authenticatedGet buyer agent request

Reads one app-request from the authenticated buyer's inbox.

Requires

authenticated

Path parameters

  • requestIdstring · uuidrequired

Response · 200

  • idstringrequired
  • connectionMethodstringrequired
  • requestCodestringrequired
  • selfReportedNamestringrequired
  • selfReportedProviderstring
  • requestedobjectrequired
  • statusstringrequired
  • expiredbooleanrequired
  • expiresAtstring
  • createdAtstring
  • resultingAgentIdstring

Errors

401 · 403 · 404 · 500 — See the error reference

httpRequest
GET /rest/v1/users/me/agents/requests/01914d0e-8192-73a4-b5b6-213243546578
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "connectionMethod": "Connection method",
  "requestCode": "Request code",
  "selfReportedName": "Self reported name",
  "selfReportedProvider": "Self reported provider",
  "requested": {},
  "status": "Status",
  "expired": false,
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "resultingAgentId": "Resulting agent id"
}
read#
POST/rest/v1/users/me/agents/requests/{requestId}/approveauthenticatedApprove buyer agent request

Approves an app-request, spawning a born-active agent with the granted scopes (⊆ requested) and optional mandate. Returns the agent id; the credential reaches the app via its own poll.

Requires

authenticated

Path parameters

  • requestIdstring · uuidrequired

Request body · application/json

  • scopesobject
  • expiryDaysintegerOne of: 30 · 90 · 365
  • mandateobject
    • perOrderCapAmountintegerrequired
    • monthlyCapAmountintegerrequired
    • scaobjectrequired
    • currencystringOne of: EUR

Response · 201

  • agentIdstringrequired

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/requests/01914d0e-a3b4-75c6-97d8-43546576879a/approve
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "scopes": {
    "browse_search": "read",
    "ordering": "read_write"
  },
  "expiryDays": 30,
  "mandate": {
    "perOrderCapAmount": 5000,
    "monthlyCapAmount": 50000,
    "sca": {
      "reference": "sca_9f2c8ab1",
      "completedAt": null
    },
    "currency": "EUR"
  }
}
jsonResponse · 201
{
  "agentId": "Agent id"
}
write#
POST/rest/v1/users/me/agents/requests/{requestId}/declineauthenticatedDecline buyer agent request

Declines an app-request from the authenticated buyer's inbox.

Requires

authenticated

Path parameters

  • requestIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/requests/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023/decline
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": null
}
write#
POST/rest/v1/users/me/agents/requests/{requestId}/dismissauthenticatedDismiss buyer agent request

Dismisses an app-request from the authenticated buyer's inbox (typically clearing an expired one).

Requires

authenticated

Path parameters

  • requestIdstring · uuidrequired

Response · 204

No content.

Errors

401 · 403 · 404 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/requests/01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01/dismiss
Authorization: Bearer $TOKEN
write#
GET/rest/v1/users/me/agents/{agentId}authenticatedGet buyer agent

Reads one of the authenticated buyer's agents in full, including scopes, mandate, and derived spend.

Requires

authenticated

Path parameters

  • agentIdstring · uuidrequired

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • expiringbooleanrequired
  • expiredbooleanrequired
  • neverUsedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • expiresAtstring
  • createdAtstring
  • scopesobjectrequired
  • requestedobject
  • credentialobjectrequired
  • mandateobject
  • spendobject

Errors

401 · 403 · 404 · 500 — See the error reference

httpRequest
GET /rest/v1/users/me/agents/01914d0e-b4c5-76d7-a8e9-546576879aab
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "expiring": false,
  "expired": false,
  "neverUsed": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "scopes": {},
  "requested": {},
  "credential": {},
  "mandate": {},
  "spend": {}
}
read#
POST/rest/v1/users/me/agents/{agentId}/accessauthenticatedChange buyer agent access

Changes an agent's scopes and/or mandate. Narrowing returns no secret; widening forces a rotation and returns a one-time secret in credential.secret. Setting ordering to read_write requires a mandate.

Requires

authenticated

Path parameters

  • agentIdstring · uuidrequired

Request body · application/json

  • scopesobject
  • mandateobject
    • perOrderCapAmountintegerrequired
    • monthlyCapAmountintegerrequired
    • scaobjectrequired
    • currencystringOne of: EUR
  • expiryDaysintegerOne of: 30 · 90 · 365 · null

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • expiringbooleanrequired
  • expiredbooleanrequired
  • neverUsedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • expiresAtstring
  • createdAtstring
  • scopesobjectrequired
  • requestedobject
  • credentialobjectrequired
  • mandateobject
  • spendobject

Errors

400 · 401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/01914d0e-6f70-7182-9394-0f1021324356/access
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "scopes": {
    "ordering": "read_write"
  },
  "mandate": {
    "perOrderCapAmount": 5000,
    "monthlyCapAmount": 50000,
    "sca": {
      "reference": "sca_9f2c8ab1",
      "completedAt": null
    },
    "currency": "EUR"
  },
  "expiryDays": 90
}
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "expiring": false,
  "expired": false,
  "neverUsed": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "scopes": {},
  "requested": {},
  "credential": {},
  "mandate": {},
  "spend": {}
}
write#
POST/rest/v1/users/me/agents/{agentId}/resumeauthenticatedResume buyer agent

Resumes a suspended buyer agent. Rejected (422) when the agent is not suspended.

Requires

authenticated

Path parameters

  • agentIdstring · uuidrequired

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • expiringbooleanrequired
  • expiredbooleanrequired
  • neverUsedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • expiresAtstring
  • createdAtstring
  • scopesobjectrequired
  • requestedobject
  • credentialobjectrequired
  • mandateobject
  • spendobject

Errors

401 · 403 · 404 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/01914d0e-92a3-74b5-86c7-324354657689/resume
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "expiring": false,
  "expired": false,
  "neverUsed": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "scopes": {},
  "requested": {},
  "credential": {},
  "mandate": {},
  "spend": {}
}
write#
POST/rest/v1/users/me/agents/{agentId}/revokeauthenticatedRevoke buyer agent

Revokes a buyer agent (terminal): disables its Keycloak client and cancels its active mandate. Idempotent — an already-revoked agent succeeds unchanged.

Requires

authenticated

Path parameters

  • agentIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • expiringbooleanrequired
  • expiredbooleanrequired
  • neverUsedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • expiresAtstring
  • createdAtstring
  • scopesobjectrequired
  • requestedobject
  • credentialobjectrequired
  • mandateobject
  • spendobject

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/01914d0e-6f70-7182-9394-0f1021324356/revoke
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": null
}
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "expiring": false,
  "expired": false,
  "neverUsed": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "scopes": {},
  "requested": {},
  "credential": {},
  "mandate": {},
  "spend": {}
}
write#
POST/rest/v1/users/me/agents/{agentId}/rotate-secretauthenticatedRotate buyer agent secret

Rotates the agent's client secret, returning the new secret once (credential.secret) with the previous secret's overlap-window expiry. Rejected (422) when the agent is revoked.

Requires

authenticated

Path parameters

  • agentIdstring · uuidrequired

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • expiringbooleanrequired
  • expiredbooleanrequired
  • neverUsedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • expiresAtstring
  • createdAtstring
  • scopesobjectrequired
  • requestedobject
  • credentialobjectrequired
  • mandateobject
  • spendobject

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/01914d0e-8192-73a4-b5b6-213243546578/rotate-secret
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "expiring": false,
  "expired": false,
  "neverUsed": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "scopes": {},
  "requested": {},
  "credential": {},
  "mandate": {},
  "spend": {}
}
write#
POST/rest/v1/users/me/agents/{agentId}/suspendauthenticatedSuspend buyer agent

Suspends an active buyer agent. Rejected (422) when the agent is not active.

Requires

authenticated

Path parameters

  • agentIdstring · uuidrequired

Request body · application/json

  • reasonstring

Response · 200

  • idstringrequired
  • clientIdstringrequired
  • namestringrequired
  • providerstring
  • surfacestringrequired
  • connectionMethodstringrequired
  • truststringrequired
  • statusstringrequired
  • expiringbooleanrequired
  • expiredbooleanrequired
  • neverUsedbooleanrequired
  • connectedAtstring
  • lastActiveAtstring
  • actorIdstringrequired
  • expiresAtstring
  • createdAtstring
  • scopesobjectrequired
  • requestedobject
  • credentialobjectrequired
  • mandateobject
  • spendobject

Errors

401 · 403 · 404 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/users/me/agents/01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12/suspend
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "reason": null
}
jsonResponse · 200
{
  "id": "Id",
  "clientId": "Client id",
  "name": "Name",
  "provider": "Provider",
  "surface": "Surface",
  "connectionMethod": "Connection method",
  "trust": "Trust",
  "status": "Status",
  "expiring": false,
  "expired": false,
  "neverUsed": false,
  "connectedAt": "Connected at",
  "lastActiveAt": "Last active at",
  "actorId": "Actor id",
  "expiresAt": "Expires at",
  "createdAt": "Created at",
  "scopes": {},
  "requested": {},
  "credential": {},
  "mandate": {},
  "spend": {}
}
write#

Marketplace API

Categories 4 operations

GET/rest/v1/categoriespublicBrowse categories

Returns a cursor-paginated list of enabled categories. In browse mode (default) items carry `hasChildren` and can be narrowed to one parent via `parentId` (omit for root categories). Providing `search` switches to a flat name-search across…

Requires

public

Query parameters

  • searchstringCase-insensitive substring match on the category name. Switches to flat search mode.
  • parentIdstring · uuidFilter by parent category ID. Omit for root categories. Ignored when `search` is provided.
  • afterstring · uuidCursor for forward pagination (UUID of last item on previous page)
  • beforestring · uuidCursor for backward pagination (UUID of first item on previous page)
  • limitinteger
  • includeTotalCountbooleanInclude total count in response metadata

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • slugstringrequired
    • pathstringrequired
    • parentIdstring · uuidrequired
    • depthintegerrequired
    • hasChildrenbooleanWhether the category has child categories. Absent/null in search mode.
  • _metadataobjectrequiredCursor-based pagination metadata
    • limitintegerrequiredRequested page size
    • hasMorebooleanrequiredWhether more items exist beyond this page
    • nextCursorstringCursor for the next page (pass as `after` query parameter)
    • prevCursorstringCursor for the previous page (pass as `before` query parameter)
    • totalCountintegerTotal item count (only present when `includeTotalCount=true`)

Errors

304 · 500 — See the error reference

httpRequest
GET /rest/v1/categories
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "name": "Electronics",
      "slug": "electronics",
      "path": "/electronics",
      "parentId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
      "depth": 0,
      "hasChildren": false
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01932a00-0000-7000-8000-000000000003",
    "prevCursor": "Prev cursor",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/categories/treepublicGet customer category tree

Returns the category tree with only enabled, visible categories. Simplified response for customer-facing views.

Requires

public

Query parameters

  • parentIdstring · uuid
  • depthinteger

Response · 200

  • idstring · uuidrequired
  • namestringrequired
  • slugstringrequired
  • descriptionstring
  • imagePathstring
  • childrenarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • slugstringrequired
    • descriptionstring
    • imagePathstring
    • childrenarray<object>required

Errors

304 · 500 — See the error reference

httpRequest
GET /rest/v1/categories/tree
Authorization: Bearer $TOKEN
jsonResponse · 200
[
  {
    "id": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
    "name": "Electronics",
    "slug": "electronics",
    "description": "Description",
    "imagePath": "Image path",
    "children": [
      {
        "id": "01914d0e-92a3-74b5-86c7-324354657689",
        "name": "Electronics",
        "slug": "electronics",
        "description": "Description",
        "imagePath": "Image path",
        "children": [
          {
            "id": "01914d0e-6f70-7182-9394-0f1021324356",
            "name": "Electronics",
            "slug": "electronics",
            "description": "Description",
            "imagePath": "Image path",
            "children": "Children"
          }
        ]
      }
    ]
  }
]
read#
GET/rest/v1/categories/{slug}publicGet category by slug path or UUID

Resolves a category by the trailing path segment and returns its details and breadcrumb trail (root to leaf, inclusive). The segment is either a UUID (resolved by id) or a slug path (e.g. "electronics/phones"); the service disambiguates by…

Requires

public

Path parameters

  • slugstringrequiredCategory slug path (e.g. "electronics/phones") or a category UUID.

Response · 200

  • idstring · uuidrequired
  • namestringrequired
  • slugstringrequired
  • descriptionstring
  • imagePathstring
  • breadcrumbarray<object>requiredBreadcrumb trail ordered root to leaf; contains only categories visible to customers (status=enabled). The last item is always the resolved category itself.
    • idstring · uuidrequired
    • namestringrequired
    • slugstringrequired

Errors

404 · 500 — See the error reference

httpRequest
GET /rest/v1/categories/Slug
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "name": "Name",
  "slug": "Slug",
  "description": "Description",
  "imagePath": "Image path",
  "breadcrumb": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "name": "Name",
      "slug": "Slug"
    }
  ]
}
read#
GET/rest/v1/public/categories/{categoryId}/attributespublicList category attributes with values (public)

Returns the attributes assigned to a category together with their enabled values, ordered by sort order. Public reference data backing the customer filter / seller listing flows (no authentication required).

Requires

public

Path parameters

  • categoryIdstring · uuidrequired

Response · 200

  • idstring · uuidrequired
  • attributeIdstring · uuidrequired
  • namestringrequired
  • handlestringrequired
  • classificationstringrequired
  • requiredbooleanrequired
  • valuesarray<object>required
    • idstring · uuidrequired
    • namestringrequired
  • sortOrderintegerrequired

Errors

500 — See the error reference

httpRequest
GET /rest/v1/public/categories/01914d0e-b4c5-76d7-a8e9-546576879aab/attributes
Authorization: Bearer $TOKEN
jsonResponse · 200
[
  {
    "id": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
    "attributeId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
    "name": "Color",
    "handle": "color",
    "classification": "product_defining",
    "required": false,
    "values": [
      {
        "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
        "name": "Black"
      }
    ],
    "sortOrder": 1
  }
]
read#

Brands 2 operations

GET/rest/v1/brandspublicBrowse brands

Returns a cursor-paginated, keyset-ordered list of surfaced brands (pending + active) as lean items ({ id, name, slug, isVerified, isOfficial, logoImageUrl }) for the seller create-listing brand picker. Supports case-insensitive substring…

Requires

public

Query parameters

  • searchstringCase-insensitive substring match on the brand name.
  • afterstring · uuidCursor for forward pagination (UUID of last item on previous page)
  • beforestring · uuidCursor for backward pagination (UUID of first item on previous page)
  • limitintegerNumber of items per page
  • includeTotalCountbooleanInclude total count in response metadata

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequired
    • namestringrequired
    • slugstringrequired
    • isVerifiedbooleanrequired
    • isOfficialbooleanrequired
    • logoImageUrlstring · uri
  • _metadataobjectrequiredCursor-based pagination metadata
    • limitintegerrequiredRequested page size
    • hasMorebooleanrequiredWhether more items exist beyond this page
    • nextCursorstringCursor for the next page (pass as `after` query parameter)
    • prevCursorstringCursor for the previous page (pass as `before` query parameter)
    • totalCountintegerTotal item count (only present when `includeTotalCount=true`)

Errors

304 · 500 — See the error reference

httpRequest
GET /rest/v1/brands
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "name": "Apple",
      "slug": "apple",
      "isVerified": false,
      "isOfficial": false,
      "logoImageUrl": "https://api.example.com"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01932a00-0000-7000-8000-000000000003",
    "prevCursor": "Prev cursor",
    "totalCount": 129900
  }
}
read#
GET/rest/v1/brands/{id}publicGet brand by ID

Resolves a single brand by its UUID, with its logo URL resolved when present. Applies no status filter -- a since-suspended brand still resolves its name and logo so an existing listing keeps rendering its brand. Returns the lean public…

Requires

public

Path parameters

  • idstring · uuidrequired

Response · 200

  • idstring · uuidrequired
  • namestringrequired
  • slugstringrequired
  • isVerifiedbooleanrequired
  • isOfficialbooleanrequired
  • logoImageUrlstring · uri

Errors

404 · 500 — See the error reference

httpRequest
GET /rest/v1/brands/01914d0e-3c4d-7e5f-a061-7c8d9e0f1023
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "name": "Apple",
  "slug": "apple",
  "isVerified": false,
  "isOfficial": false,
  "logoImageUrl": "https://api.example.com"
}
read#

Public Products 1 operation

GET/rest/v1/products/{productId}publicGet customer product detail

Returns a customer-facing product detail with the three-tier hierarchy: product info, published variants, and qualifying offers per variant. Only approved and non-disabled products are returned. No authentication required.

Requires

public

Path parameters

  • productIdstring · uuidrequiredProduct UUID

Query parameters

  • variantIdstring · uuidPre-select a specific variant by UUID

Response · 200

  • idstring · uuidrequiredProduct ID
  • titlestringrequiredProduct title
  • descriptionstringProduct description
  • categoryIdstring · uuidrequiredCategory ID
  • categoryBreadcrumbarray<object>requiredCategory trail ordered root to leaf, containing only categories visible to customers (status=enabled); disabled ancestors are omitted. The last item is always the product's own category, even when that category is disabled. Always present…
    • idstring · uuidrequired
    • namestringrequired
    • slugstringrequired
  • mediaarray<object>requiredProduct media ordered by position
    • idstring · uuidrequired
    • pathstringrequiredMedia file path
    • positionintegerrequiredDisplay order (0-based)
    • altTextstringAlt text for accessibility
  • productAttributesarray<object>requiredAssigned product attribute value pairs
    • attributeIdstring · uuidrequired
    • attributeValueIdstring · uuidrequired
  • optionsarray<object>requiredVariant axis definitions (e.g., Color, Size)
    • namestringrequiredOption name (e.g., Color, Size)
    • valuesarray<object>requiredAvailable values for this option
  • variantsarray<object>requiredPublished variants with aggregated offer data
    • variantIdstring · uuidrequiredMarketplace variant ID
    • axisValuesobjectrequiredMap of option name to value text (e.g., {"Color":"Red","Size":"M"})
    • primaryImageUrlstringConvenience alias for the first media item's URL; null when the variant has no media.
    • mediaarray<object>Full position-ordered variant media gallery.
    • minPriceintegerrequiredLowest price among qualifying offers in cents
    • offerCountintegerrequiredNumber of qualifying offers for this variant
    • sellerCountintegerrequiredNumber of distinct sellers with qualifying offers
    • hasPriceRangebooleanrequiredWhether offers span multiple price points
    • inStockbooleanrequiredWhether at least one qualifying offer is in stock
    • displayOrderintegerrequiredDisplay order (1-based)
    • offersarray<object>requiredQualifying offers for this variant
  • defaultVariantIdstring · uuidrequiredDefault variant ID
  • preSelectedVariantIdstring · uuidPre-selected variant ID (when variantId query param was provided)

Errors

404 · 500 — See the error reference

httpRequest
GET /rest/v1/products/01914d0e-7081-7293-a4a5-102132435467
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-8192-73a4-b5b6-213243546578",
  "title": "Title",
  "description": "Description",
  "categoryId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "categoryBreadcrumb": [
    {
      "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "name": "Name",
      "slug": "Slug"
    }
  ],
  "media": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "path": "Path",
      "position": 0,
      "altText": "Alt text"
    }
  ],
  "productAttributes": [
    {
      "attributeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "attributeValueId": "01914d0e-b4c5-76d7-a8e9-546576879aab"
    }
  ],
  "options": [
    {
      "name": "Name",
      "values": [
        {
          "id": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "value": "Value",
          "position": 0
        }
      ]
    }
  ],
  "variants": [
    {
      "variantId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
      "axisValues": {},
      "primaryImageUrl": "Primary image url",
      "media": [
        {
          "id": "01914d0e-a3b4-75c6-97d8-43546576879a",
          "url": "Url",
          "position": 0,
          "altText": "Alt text"
        }
      ],
      "minPrice": 1999,
      "offerCount": 0,
      "sellerCount": 0,
      "hasPriceRange": false,
      "inStock": false,
      "displayOrder": 0,
      "offers": [
        {
          "listingVariantId": "01914d0e-6f70-7182-9394-0f1021324356",
          "storeId": "01914d0e-c5d6-77e8-b9fa-6576879aabbc",
          "sellerId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
          "sellerName": "Seller name",
          "priceAmount": 2499,
          "priceCurrency": "EUR",
          "stockStatus": "in_stock",
          "fulfillmentMethods": [
            "delivery",
            "pickup"
          ],
          "condition": "Condition",
          "logoUrl": "Logo url",
          "photos": [
            {}
          ]
        }
      ]
    }
  ],
  "defaultVariantId": "01914d0e-a3b4-75c6-97d8-43546576879a",
  "preSelectedVariantId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023"
}
read#

Feedback 4 operations

GET/rest/v1/feedback/bug-reports/challengeauthenticatedIssue a bug-report proof

Issues a short-lived signed proof the bug-report window must wait on and then send back with one report as `widget.token`. The proof is bound to the signed-in person and to the marketplace web app their token was issued to, it is single…

Requires

authenticated

Response · 200

  • tokenstringrequiredOpaque signed proof. Send it back unchanged as `widget.token` on the report POST, no sooner than `waitMs` and no later than `ttlMs` after it was issued. Never store it or put it in a URL.
  • waitMsintegerrequiredMinimum age in milliseconds before the proof is accepted.
  • ttlMsintegerrequiredLifetime of the proof in milliseconds.

Errors

401 · 403 · 429 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/feedback/bug-reports/challenge
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "token": "Token",
  "waitMs": 2000,
  "ttlMs": 900000
}
read#
POST/rest/v1/feedback/bug-reportsauthenticatedFile a bug report

Files one report from the bug-report window as a confidential issue for the platform team and answers with the number it was filed under. The body is the window's report — `type`, `description`, optional `attachments` as base64, `diag` and…

Requires

authenticated

Request body · application/json

  • typestringAnything else is filed as `bug`.One of: bug · feature · feedback
  • descriptionstringrequired
  • attachmentsarray<object>Images (PNG, JPEG, GIF, WebP), PDF, video (MP4, MOV, WebM) and UTF-8 text files, typed by their bytes; up to 10 MB each and 20 MB together, text files up to 1 MB together.
    • namestring
    • mimestring
    • datastring · byterequired
  • diagstringDiagnostics the reporter chose to attach; scrubbed again by the server.
  • contextobjectPage context; only an allowlisted set of keys reaches the issue.
  • widgetobjectrequired
    • versionintegerrequired
    • tokenstringrequiredThe proof from the challenge GET.
    • websitestringrequiredMust be empty.

Response · 201

  • iidintegerrequiredThe number the report was filed under; the window shows it as `#412` and lists it under My reports.

Errors

400 · 401 · 403 · 411 · 413 · 429 · 500 · 502 · 503 — See the error reference

httpRequest
POST /rest/v1/feedback/bug-reports
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "type": "bug",
  "description": "The Save button does nothing on the store settings page.",
  "attachments": [
    {
      "name": "screenshot.png",
      "mime": "image/png",
      "data": "Data"
    }
  ],
  "diag": "Diag",
  "context": {},
  "widget": {
    "version": 1,
    "token": "Token",
    "website": ""
  }
}
jsonResponse · 201
{
  "iid": 412
}
write#
GET/rest/v1/feedback/bug-reports/mineauthenticatedList my bug reports

Lists the reports the signed-in person filed from this app through the bug-report window, newest first and at most 50, with their status (`new`, `doing`, `fixed`, `rejected`) and the number of replies they may read. Only issues this…

Requires

authenticated

Response · 200

  • reportsarray<object>requiredThe signed-in person's own reports from this app, newest first, at most 50.
    • iidintegerrequired
    • titlestringrequired
    • typestringrequiredOne of: bug · feature · feedback
    • statusstringrequiredOne of: new · doing · fixed · rejected
    • created_atstring · date-timerequired
    • updated_atstring · date-timerequired
    • urlstringrequiredAlways empty. Reports are confidential issues a reporter cannot open, so no address is given.
    • commentsintegerrequiredReplies the reporter may read.

Errors

401 · 403 · 429 · 500 · 502 · 503 — See the error reference

httpRequest
GET /rest/v1/feedback/bug-reports/mine
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "reports": [
    {
      "iid": 412,
      "title": "The Save button does nothing",
      "type": "bug",
      "status": "new",
      "created_at": "2026-09-10T09:24:11Z",
      "updated_at": "2026-09-10T09:24:11Z",
      "url": "",
      "comments": 1
    }
  ]
}
read#
GET/rest/v1/feedback/bug-reports/mine/{iid}/commentsauthenticatedList the replies on my bug report

Lists the replies on one of the signed-in person's own reports, oldest first and at most 100. The report is read again and its reporter checked on every call, so a report filed by anyone else, from another app, or as an issue this service…

Requires

authenticated

Path parameters

  • iidintegerrequiredThe report number.

Response · 200

  • commentsarray<object>requiredReplies on the report, oldest first, at most 100. Internal and system notes are never included.
    • authorstringrequired
    • bodystringrequired
    • created_atstring · date-timerequired

Errors

401 · 403 · 404 · 429 · 500 · 502 · 503 — See the error reference

httpRequest
GET /rest/v1/feedback/bug-reports/mine/0/comments
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "comments": [
    {
      "author": "Platform team",
      "body": "Fixed in today's release, thank you.",
      "created_at": "2026-09-10T09:24:11Z"
    }
  ]
}
read#

Platform 2 operations

GET/rest/v1/platform/countriespublicList supported countries

Returns the list of countries supported by the platform. Static reference data -- no authentication required.

Requires

public

Response · 200

  • codestringrequiredISO 3166-1 alpha-2 country code
  • namestringrequiredEnglish country name

Errors

500 — See the error reference

httpRequest
GET /rest/v1/platform/countries
Authorization: Bearer $TOKEN
jsonResponse · 200
[
  {
    "code": "LT",
    "name": "Lithuania"
  }
]
read#
GET/rest/v1/platform/countries/{countryCode}/citiespublicList cities for a country

Returns the browsable cities for a supported country, used by the storefront browsing-location picker. Static reference data -- no authentication required; cached for one hour. A supported country with no dataset returns an empty list.

Requires

public

Path parameters

  • countryCodestringrequiredISO 3166-1 alpha-2 country code (case-insensitive)

Response · 200

  • citiesarray<object>required
    • namestringrequiredCity name
    • slugstringrequiredURL-safe city identifier

Errors

404 · 500 — See the error reference

httpRequest
GET /rest/v1/platform/countries/Country code/cities
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "cities": [
    {
      "name": "Vilnius",
      "slug": "vilnius"
    }
  ]
}
read#

Discovery API

Discovery 6 operations

GET/rest/v1/discovery/feedpublicDiscovery feed

Curated product feed for the homepage. Returns recently listed products with cursor-based pagination.

Requires

public

Query parameters

  • limitintegerMaximum number of items to return.
  • cursorstringOpaque cursor for fetching the next page, taken from a prior response's `_metadata.nextCursor`. A cursor the service does not recognise is ignored and the feed restarts at the first page -- it is never rejected. See…

Response · 200

  • itemsarray<object>requiredList of product cards for the current page.
    • productIdstringrequiredUnique product identifier.
    • titlestringrequiredProduct display title.
    • primaryImageUrlstring · urirequiredURL of the primary product image.
    • minPriceintegerrequiredLowest available price in cents. `0` means the product has no priced offer behind it -- it is not a free product. On the browse and feed paths such a product can appear in a price-sorted grid, where it is placed at the END under both price…
    • hasPriceRangebooleanrequiredWhether multiple offers exist with different prices.
    • offerCountintegerrequiredNumber of active seller offers for this product.
    • stockStatusstringrequiredAggregate stock availability status.One of: in_stock · out_of_stock
    • conditionsarray<string>requiredDistinct item-condition value names available across the product's qualifying offers (e.g., New, Refurbished, Used). Matches the values accepted by the `condition` search filter.
    • reachableCountriesarray<string>requiredISO 3166-1 alpha-2 country codes that the product's qualifying offers can deliver to or be picked up in. Drives the `destination` search filter's reachability check.
    • pickupPointsarray<object>requiredSeller pickup locations projected from the qualifying offers' fulfillment data.
  • _metadataobjectrequired
    • limitintegerrequiredRequested page size.
    • hasMorebooleanrequiredWhether more items exist beyond the current page.
    • nextCursorstringOpaque cursor to pass for the next page (`?cursor=`). Null when no more pages. Treat it as an opaque token -- do NOT parse it, build one, or read an identifier out of it. The only supported source of a cursor is this field on a prior…
    • totalCountintegerCount of retrievable results behind the current result set. On the query (NL search) path this is always populated (never null): for a single-intent search it is the size of the fused, relevance-cutoff- passing candidate pool (a lower…
  • filtersAppliedobjectSummary of filters that were applied to produce this result set.
    • categoryobjectCategory filter that was applied. Null when no category was requested, or when an AI-predicted category id from a natural language query was unresolvable against the catalog cache and was dropped (the search then degrades to full-text plus…
    • priceMinintegerApplied lower price bound in cents (inclusive). Reflects the effective bound after merging the explicit `filters.priceMin` with any bound parsed from the natural-language query (e.g. "over 200"). Price bounds are never relaxed, so this…
    • priceMaxintegerApplied upper price bound in cents (inclusive). Reflects the effective bound after merging the explicit `filters.priceMax` with any bound parsed from the natural-language query (e.g. "under 300", "cheap"). Price bounds are never relaxed…
    • attributesarray<object>Applied attribute filters. Includes both enforced attributes and relaxed ones (each carrying its own `relaxed` flag) so the UI can render the full set of chips the query implied.
    • conditionstringThe item-condition value that was applied, if any.
    • destinationCountrystringThe destination country code that was applied for the reachable-countries filter, if any.
    • textQuerystringThe text query that was interpreted, if any.
  • explanationstringHuman-readable summary of how an NL query was interpreted (null on the pure browse/feed paths). For a single-intent search it names, in order, the intent label, the category (only when it survived the population guard), the price bounds…
  • relaxedItemsarray<object>A secondary set of near-miss products, populated (not just declared) when the strict result grid comes back thin. It is produced ONLY on the NL query path and ONLY when all of these hold: it is the first page (no cursor), the strict page…
    • productIdstringrequiredUnique product identifier.
    • titlestringrequiredProduct display title.
    • primaryImageUrlstring · urirequiredURL of the primary product image.
    • minPriceintegerrequiredLowest available price in cents. `0` means the product has no priced offer behind it -- it is not a free product. On the browse and feed paths such a product can appear in a price-sorted grid, where it is placed at the END under both price…
    • hasPriceRangebooleanrequiredWhether multiple offers exist with different prices.
    • offerCountintegerrequiredNumber of active seller offers for this product.
    • stockStatusstringrequiredAggregate stock availability status.One of: in_stock · out_of_stock
    • conditionsarray<string>requiredDistinct item-condition value names available across the product's qualifying offers (e.g., New, Refurbished, Used). Matches the values accepted by the `condition` search filter.
    • reachableCountriesarray<string>requiredISO 3166-1 alpha-2 country codes that the product's qualifying offers can deliver to or be picked up in. Drives the `destination` search filter's reachability check.
    • pickupPointsarray<object>requiredSeller pickup locations projected from the qualifying offers' fulfillment data.

Errors

422 — See the error reference

httpRequest
GET /rest/v1/discovery/feed
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "productId": "Product id",
      "title": "Title",
      "primaryImageUrl": "https://api.example.com",
      "minPrice": 129900,
      "hasPriceRange": false,
      "offerCount": 0,
      "stockStatus": "in_stock",
      "conditions": [],
      "reachableCountries": [],
      "pickupPoints": []
    }
  ],
  "_metadata": {
    "limit": 0,
    "hasMore": false,
    "nextCursor": "Next cursor",
    "totalCount": 129900
  },
  "filtersApplied": {
    "category": {
      "id": "Id",
      "name": "Name"
    },
    "priceMin": 129900,
    "priceMax": 129900,
    "attributes": [
      {
        "id": "Id",
        "name": "Name",
        "values": [
          "Values"
        ],
        "relaxed": false
      }
    ],
    "condition": "Condition",
    "destinationCountry": "Destination country",
    "textQuery": "Text query"
  },
  "explanation": "Explanation",
  "relaxedItems": [
    {
      "productId": "Product id",
      "title": "Title",
      "primaryImageUrl": "https://api.example.com",
      "minPrice": 129900,
      "hasPriceRange": false,
      "offerCount": 0,
      "stockStatus": "in_stock",
      "conditions": [],
      "reachableCountries": [],
      "pickupPoints": []
    }
  ]
}
read#
GET/rest/v1/discovery/categoriespublicCategory tree

Returns the browsable category tree, optionally scoped to a parent category and limited to a specific depth.

Requires

public

Query parameters

  • parentIdstringID of the parent category. When provided, only children of this category are returned.
  • depthintegerMaximum depth of the category tree to return.

Response · 200

  • itemsarray<object>requiredTop-level category nodes (or children of the requested parent).
    • idstringrequiredUnique category identifier.
    • namestringrequiredDisplay name of the category.
    • slugstringrequiredURL-friendly slug.
    • imageUrlstring · uriCategory image URL.
    • productCountintegerNumber of products in this category.
    • childrenarray<object>Child categories forming a tree structure.

Errors

422 — See the error reference

httpRequest
GET /rest/v1/discovery/categories
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "Id",
      "name": "Name",
      "slug": "Slug",
      "imageUrl": "https://api.example.com",
      "productCount": 0,
      "children": []
    }
  ]
}
read#
GET/rest/v1/discovery/filterspublicFilter metadata

Returns available filter options (sort orders, price range, filterable attributes with per-value product counts) for a given browsing context. Use the returned metadata to build filter UI for the browse endpoint -- each attribute's `id` is…

Requires

public

Query parameters

  • categoryIdstringCategory ID to scope the available filters. When omitted (and no `categorySlug`), returns global filter options.
  • categorySlugstringCategory URL slug to scope the available filters, resolved to a canonical category id server-side. An alternative to `categoryId`; a slug that does not resolve degrades gracefully to global metadata.

Response · 200

  • sortOptionsarray<object>requiredAvailable sort orders.
    • valuestringrequiredMachine-readable sort key to pass in browse requests.
    • labelstringrequiredHuman-readable label for display.
  • priceRangeobjectPrice bounds in the current scope.
    • minAvailableintegerrequiredLowest price in the current scope (cents).
    • maxAvailableintegerrequiredHighest price in the current scope (cents).
  • categoryobjectCurrent category context, if scoped.
    • currentIdstringID of the currently selected category.
    • currentNamestringDisplay name of the currently selected category.
  • attributesarray<object>requiredFilterable attributes with their available values.
    • idstringrequiredThe attribute's stable handle -- the `product_attributes` JSONB key and the suffix of the `attr_{handle}` browse query parameter (pass `attr_brand=Sony` to filter by this attribute). Not a display label; use `name` for that.
    • namestringrequiredHuman-readable attribute name for display.
    • valuesarray<object>requiredAvailable values for this attribute in the current category scope, each with its product count (a `{value, count}` object -- no longer a bare string).

Errors

422 — See the error reference

httpRequest
GET /rest/v1/discovery/filters
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "sortOptions": [
    {
      "value": "Value",
      "label": "Label"
    }
  ],
  "priceRange": {
    "minAvailable": 0,
    "maxAvailable": 0
  },
  "category": {
    "currentId": "Current id",
    "currentName": "Current name"
  },
  "attributes": [
    {
      "id": "Id",
      "name": "Name",
      "values": [
        {
          "value": "Value",
          "count": 0
        }
      ]
    }
  ]
}
read#
GET/rest/v1/discovery/browsepublicCategory browse

Browse products by category with optional attribute filters and sorting. Returns paginated product cards with an applied-filter summary. The category is identified by EITHER `categoryId` OR `categorySlug` -- at least one is required, and a…

Requires

public

Query parameters

  • categoryIdstringID of the category to browse. Provide this OR `categorySlug` (at least one is required; when both are given, `categoryId` takes precedence).
  • categorySlugstringURL slug of the category to browse (e.g. the `mobile-smart-phones` path segment), resolved to a canonical category id server-side. Provide this OR `categoryId`.
  • sortstringSort order for results. Defaults to `recency` on the browse path. In-stock products always rank ahead of out-of-stock ones, before the chosen sort is applied. A product with no priced offer reports `minPrice: 0` and sorts to the END of the…One of: recency · price_asc · price_desc
  • priceMinintegerMinimum price filter in cents (inclusive).
  • priceMaxintegerMaximum price filter in cents (inclusive).
  • attr_{handle}stringAttribute facet filter, keyed by the attribute handle returned as `FilterableAttribute.id` from `/filters` (e.g. `attr_brand=Sony`). Repeat the same parameter to OR multiple values within one attribute (`attr_brand=Sony&attr_brand=Bose`)…
  • limitintegerMaximum number of items to return.
  • cursorstringOpaque cursor for fetching the next page, taken from a prior response's `_metadata.nextCursor`. Replay it against an otherwise identical request -- same `sort`, same filters. A cursor the service does not recognise is ignored and browsing…
  • includeTotalCountbooleanWhen true, populates `_metadata.totalCount` with an exact `COUNT` over the same filters. Omitted/false leaves `totalCount` null.

Response · 200

  • itemsarray<object>requiredList of product cards for the current page.
    • productIdstringrequiredUnique product identifier.
    • titlestringrequiredProduct display title.
    • primaryImageUrlstring · urirequiredURL of the primary product image.
    • minPriceintegerrequiredLowest available price in cents. `0` means the product has no priced offer behind it -- it is not a free product. On the browse and feed paths such a product can appear in a price-sorted grid, where it is placed at the END under both price…
    • hasPriceRangebooleanrequiredWhether multiple offers exist with different prices.
    • offerCountintegerrequiredNumber of active seller offers for this product.
    • stockStatusstringrequiredAggregate stock availability status.One of: in_stock · out_of_stock
    • conditionsarray<string>requiredDistinct item-condition value names available across the product's qualifying offers (e.g., New, Refurbished, Used). Matches the values accepted by the `condition` search filter.
    • reachableCountriesarray<string>requiredISO 3166-1 alpha-2 country codes that the product's qualifying offers can deliver to or be picked up in. Drives the `destination` search filter's reachability check.
    • pickupPointsarray<object>requiredSeller pickup locations projected from the qualifying offers' fulfillment data.
  • _metadataobjectrequired
    • limitintegerrequiredRequested page size.
    • hasMorebooleanrequiredWhether more items exist beyond the current page.
    • nextCursorstringOpaque cursor to pass for the next page (`?cursor=`). Null when no more pages. Treat it as an opaque token -- do NOT parse it, build one, or read an identifier out of it. The only supported source of a cursor is this field on a prior…
    • totalCountintegerCount of retrievable results behind the current result set. On the query (NL search) path this is always populated (never null): for a single-intent search it is the size of the fused, relevance-cutoff- passing candidate pool (a lower…
  • filtersAppliedobjectSummary of filters that were applied to produce this result set.
    • categoryobjectCategory filter that was applied. Null when no category was requested, or when an AI-predicted category id from a natural language query was unresolvable against the catalog cache and was dropped (the search then degrades to full-text plus…
    • priceMinintegerApplied lower price bound in cents (inclusive). Reflects the effective bound after merging the explicit `filters.priceMin` with any bound parsed from the natural-language query (e.g. "over 200"). Price bounds are never relaxed, so this…
    • priceMaxintegerApplied upper price bound in cents (inclusive). Reflects the effective bound after merging the explicit `filters.priceMax` with any bound parsed from the natural-language query (e.g. "under 300", "cheap"). Price bounds are never relaxed…
    • attributesarray<object>Applied attribute filters. Includes both enforced attributes and relaxed ones (each carrying its own `relaxed` flag) so the UI can render the full set of chips the query implied.
    • conditionstringThe item-condition value that was applied, if any.
    • destinationCountrystringThe destination country code that was applied for the reachable-countries filter, if any.
    • textQuerystringThe text query that was interpreted, if any.
  • explanationstringHuman-readable summary of how an NL query was interpreted (null on the pure browse/feed paths). For a single-intent search it names, in order, the intent label, the category (only when it survived the population guard), the price bounds…
  • relaxedItemsarray<object>A secondary set of near-miss products, populated (not just declared) when the strict result grid comes back thin. It is produced ONLY on the NL query path and ONLY when all of these hold: it is the first page (no cursor), the strict page…
    • productIdstringrequiredUnique product identifier.
    • titlestringrequiredProduct display title.
    • primaryImageUrlstring · urirequiredURL of the primary product image.
    • minPriceintegerrequiredLowest available price in cents. `0` means the product has no priced offer behind it -- it is not a free product. On the browse and feed paths such a product can appear in a price-sorted grid, where it is placed at the END under both price…
    • hasPriceRangebooleanrequiredWhether multiple offers exist with different prices.
    • offerCountintegerrequiredNumber of active seller offers for this product.
    • stockStatusstringrequiredAggregate stock availability status.One of: in_stock · out_of_stock
    • conditionsarray<string>requiredDistinct item-condition value names available across the product's qualifying offers (e.g., New, Refurbished, Used). Matches the values accepted by the `condition` search filter.
    • reachableCountriesarray<string>requiredISO 3166-1 alpha-2 country codes that the product's qualifying offers can deliver to or be picked up in. Drives the `destination` search filter's reachability check.
    • pickupPointsarray<object>requiredSeller pickup locations projected from the qualifying offers' fulfillment data.

Errors

422 — See the error reference

httpRequest
GET /rest/v1/discovery/browse
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "productId": "Product id",
      "title": "Title",
      "primaryImageUrl": "https://api.example.com",
      "minPrice": 129900,
      "hasPriceRange": false,
      "offerCount": 0,
      "stockStatus": "in_stock",
      "conditions": [],
      "reachableCountries": [],
      "pickupPoints": []
    }
  ],
  "_metadata": {
    "limit": 0,
    "hasMore": false,
    "nextCursor": "Next cursor",
    "totalCount": 129900
  },
  "filtersApplied": {
    "category": {
      "id": "Id",
      "name": "Name"
    },
    "priceMin": 129900,
    "priceMax": 129900,
    "attributes": [
      {
        "id": "Id",
        "name": "Name",
        "values": [
          "Values"
        ],
        "relaxed": false
      }
    ],
    "condition": "Condition",
    "destinationCountry": "Destination country",
    "textQuery": "Text query"
  },
  "explanation": "Explanation",
  "relaxedItems": [
    {
      "productId": "Product id",
      "title": "Title",
      "primaryImageUrl": "https://api.example.com",
      "minPrice": 129900,
      "hasPriceRange": false,
      "offerCount": 0,
      "stockStatus": "in_stock",
      "conditions": [],
      "reachableCountries": [],
      "pickupPoints": []
    }
  ]
}
read#
POST/rest/v1/discovery/searchpublicNatural language search

Accepts a natural language query and/or structured filters. Returns matching products with applied filter details. At least one of `query` or `filters` must be provided. When a `query` is present it is parsed for intent -- category, price…

Requires

public

Query parameters

  • limitintegerMaximum number of items to return.
  • cursorstringOpaque cursor for fetching the next page, taken from a prior response's `_metadata.nextCursor`. Replay it against an otherwise identical request -- same `query`, same `filters` (including `sort` and `destination`). A cursor the service…
  • includeTotalCountbooleanOnly affects the pure browse path (a request with `filters` but no `query`), where it adds an exact `COUNT`. On the query path `totalCount` is always computed regardless of this flag.

Request body · application/json

  • querystringNatural language search query.
  • filtersobjectStructured filter criteria.
    • categoryIdstringFilter by category ID.
    • priceMinintegerMinimum price filter in cents (inclusive).
    • priceMaxintegerMaximum price filter in cents (inclusive).
    • attributesobjectAttribute filters as key-value pairs. Keys are attribute IDs, values are lists of accepted values.
    • conditionstringItem-condition value name to filter by (e.g., New, Refurbished, Used). Applied as an array-containment match against each product's projected `conditions` (`conditions @> [value]`).
    • destinationobjectBuyer delivery destination used to scope results to reachable offers. The `country` code drives a reachable-countries containment filter; `lat`/`lng` are accepted for future pickup-proximity ranking and are not yet applied as a filter.
    • sortstringRequested result ordering, or null to let the service decide. It is honoured on BOTH the browse and the NL query path. Sort precedence is: an explicit value here always wins; otherwise a superlative parsed from the natural-language query…One of: recency · price_asc · price_desc

Response · 200

  • itemsarray<object>requiredList of product cards for the current page.
    • productIdstringrequiredUnique product identifier.
    • titlestringrequiredProduct display title.
    • primaryImageUrlstring · urirequiredURL of the primary product image.
    • minPriceintegerrequiredLowest available price in cents. `0` means the product has no priced offer behind it -- it is not a free product. On the browse and feed paths such a product can appear in a price-sorted grid, where it is placed at the END under both price…
    • hasPriceRangebooleanrequiredWhether multiple offers exist with different prices.
    • offerCountintegerrequiredNumber of active seller offers for this product.
    • stockStatusstringrequiredAggregate stock availability status.One of: in_stock · out_of_stock
    • conditionsarray<string>requiredDistinct item-condition value names available across the product's qualifying offers (e.g., New, Refurbished, Used). Matches the values accepted by the `condition` search filter.
    • reachableCountriesarray<string>requiredISO 3166-1 alpha-2 country codes that the product's qualifying offers can deliver to or be picked up in. Drives the `destination` search filter's reachability check.
    • pickupPointsarray<object>requiredSeller pickup locations projected from the qualifying offers' fulfillment data.
  • _metadataobjectrequired
    • limitintegerrequiredRequested page size.
    • hasMorebooleanrequiredWhether more items exist beyond the current page.
    • nextCursorstringOpaque cursor to pass for the next page (`?cursor=`). Null when no more pages. Treat it as an opaque token -- do NOT parse it, build one, or read an identifier out of it. The only supported source of a cursor is this field on a prior…
    • totalCountintegerCount of retrievable results behind the current result set. On the query (NL search) path this is always populated (never null): for a single-intent search it is the size of the fused, relevance-cutoff- passing candidate pool (a lower…
  • filtersAppliedobjectSummary of filters that were applied to produce this result set.
    • categoryobjectCategory filter that was applied. Null when no category was requested, or when an AI-predicted category id from a natural language query was unresolvable against the catalog cache and was dropped (the search then degrades to full-text plus…
    • priceMinintegerApplied lower price bound in cents (inclusive). Reflects the effective bound after merging the explicit `filters.priceMin` with any bound parsed from the natural-language query (e.g. "over 200"). Price bounds are never relaxed, so this…
    • priceMaxintegerApplied upper price bound in cents (inclusive). Reflects the effective bound after merging the explicit `filters.priceMax` with any bound parsed from the natural-language query (e.g. "under 300", "cheap"). Price bounds are never relaxed…
    • attributesarray<object>Applied attribute filters. Includes both enforced attributes and relaxed ones (each carrying its own `relaxed` flag) so the UI can render the full set of chips the query implied.
    • conditionstringThe item-condition value that was applied, if any.
    • destinationCountrystringThe destination country code that was applied for the reachable-countries filter, if any.
    • textQuerystringThe text query that was interpreted, if any.
  • explanationstringHuman-readable summary of how an NL query was interpreted (null on the pure browse/feed paths). For a single-intent search it names, in order, the intent label, the category (only when it survived the population guard), the price bounds…
  • relaxedItemsarray<object>A secondary set of near-miss products, populated (not just declared) when the strict result grid comes back thin. It is produced ONLY on the NL query path and ONLY when all of these hold: it is the first page (no cursor), the strict page…
    • productIdstringrequiredUnique product identifier.
    • titlestringrequiredProduct display title.
    • primaryImageUrlstring · urirequiredURL of the primary product image.
    • minPriceintegerrequiredLowest available price in cents. `0` means the product has no priced offer behind it -- it is not a free product. On the browse and feed paths such a product can appear in a price-sorted grid, where it is placed at the END under both price…
    • hasPriceRangebooleanrequiredWhether multiple offers exist with different prices.
    • offerCountintegerrequiredNumber of active seller offers for this product.
    • stockStatusstringrequiredAggregate stock availability status.One of: in_stock · out_of_stock
    • conditionsarray<string>requiredDistinct item-condition value names available across the product's qualifying offers (e.g., New, Refurbished, Used). Matches the values accepted by the `condition` search filter.
    • reachableCountriesarray<string>requiredISO 3166-1 alpha-2 country codes that the product's qualifying offers can deliver to or be picked up in. Drives the `destination` search filter's reachability check.
    • pickupPointsarray<object>requiredSeller pickup locations projected from the qualifying offers' fulfillment data.

Errors

422 — See the error reference

httpRequest
POST /rest/v1/discovery/search
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "query": "Query",
  "filters": {
    "categoryId": "Category id",
    "priceMin": 129900,
    "priceMax": 129900,
    "attributes": {},
    "condition": "Condition",
    "destination": {
      "country": "Country",
      "lat": 0,
      "lng": 0
    },
    "sort": "recency"
  }
}
jsonResponse · 200
{
  "items": [
    {
      "productId": "Product id",
      "title": "Title",
      "primaryImageUrl": "https://api.example.com",
      "minPrice": 129900,
      "hasPriceRange": false,
      "offerCount": 0,
      "stockStatus": "in_stock",
      "conditions": [],
      "reachableCountries": [],
      "pickupPoints": []
    }
  ],
  "_metadata": {
    "limit": 0,
    "hasMore": false,
    "nextCursor": "Next cursor",
    "totalCount": 129900
  },
  "filtersApplied": {
    "category": {
      "id": "Id",
      "name": "Name"
    },
    "priceMin": 129900,
    "priceMax": 129900,
    "attributes": [
      {
        "id": "Id",
        "name": "Name",
        "values": [
          "Values"
        ],
        "relaxed": false
      }
    ],
    "condition": "Condition",
    "destinationCountry": "Destination country",
    "textQuery": "Text query"
  },
  "explanation": "Explanation",
  "relaxedItems": [
    {
      "productId": "Product id",
      "title": "Title",
      "primaryImageUrl": "https://api.example.com",
      "minPrice": 129900,
      "hasPriceRange": false,
      "offerCount": 0,
      "stockStatus": "in_stock",
      "conditions": [],
      "reachableCountries": [],
      "pickupPoints": []
    }
  ]
}
write#
GET/rest/v1/discovery/suggestionspublicSearch suggestions

Returns ranked typeahead suggestions for the buyer search box: the vocabulary is rebuilt from the approved catalog once per day, omitting `q` returns the popular set, and items with `type: category` must be opened via their `ref` (category…

Requires

public

Query parameters

  • qstringPartial buyer input. Never produces a validation error: below the two-character minimum (absent, blank, whitespace-only, or a single character) the popular set is returned; a longer query that matches nothing returns an empty list; input…
  • limitintegerMaximum number of suggestions to return.

Response · 200

  • itemsarray<object>requiredRanked suggestions, capped at `limit`. Empty when nothing matches or the vocabulary has not been built yet.
    • textstringrequiredDisplay text of the suggestion, shown verbatim in the typeahead list.
    • typestringrequiredWhat the suggestion points at. `product` and `brand` items are submitted as free-text search; `category` items are opened via `ref`.One of: product · brand · category
    • refstringCategory slug for `category` items, used to open category browse. Always `null` for `product` and `brand` items.

Errors

422 — See the error reference

httpRequest
GET /rest/v1/discovery/suggestions
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "text": "Text",
      "type": "product",
      "ref": "Ref"
    }
  ]
}
read#

Matching 5 operations

POST/rest/v1/matching/identifyproducts:readIdentify and ground a product (the consolidated Identify endpoint)

The flagship seller-facing Identify -> Ground pass. From a free-text query, one or more barcodes, or an uploaded photo it produces a single `GroundedIdentification`: a resolved category, brand, grounded attributes, variant + custom…

Requires

products:read

Request body · application/json

  • querystringFree-text description of the product to identify.
  • barcodesarray<string>Barcodes for the deterministic fast path (EAN-13, UPC-A, ...). A valid barcode skips the LLM identification call.

Response · 200

  • categoryIdstringResolved leaf category id, or null when unresolved.
  • categoryPatharray<string>
  • brandIdstringResolved brand id, or null when unresolved.
  • brandNamestring
  • titlestring
  • descriptionstring
  • groundedAttributesarray<object>
    • handlestringrequired
    • valueIdstring
    • typedValuestring
    • confidencenumber · doublerequired
  • variantOptionsarray<object>
    • namestringrequired
    • valuesarray<string>
  • customOptionsarray<object>
    • namestringrequired
    • valuesarray<string>Optional -- a custom option may be free-text (no enumerated values).
  • physicalobjectPhysical dimensions in canonical integer units -- millimetres and grams. Every field is optional: grounding fills what it can validate and routes the rest to `unresolved`. Floats are deliberately disallowed to avoid rounding drift.
    • weightGramsinteger
    • lengthMminteger
    • widthMminteger
    • heightMminteger
  • priceBandobjectAn offer-level price estimate in integer cents with an explicit derivation basis. `basis=offers` when the band is grounded in qualifying-offer aggregates of a matched family; `basis=model` when it is an LLM estimate carried with a…
    • minCentsinteger
    • maxCentsinteger
    • suggestedCentsinteger
    • currencystringrequiredISO 4217 currency code.
    • basisstringrequiredHow the band was derived: `offers` (grounded in a matched family's qualifying offers) or `model` (LLM estimate, confidence-discounted).One of: offers · model
    • confidencenumber · doublerequiredConfidence in the price band (0.0 to 1.0).
  • barcodesarray<string>
  • unresolvedarray<object>Fields the grounding layer could not resolve, each carrying the model's proposed string (invariant 1).
    • fieldstringrequiredLogical field name (e.g. brand, category, weightGrams).
    • proposedstringrequiredThe model's proposed value that could not be grounded.
    • reasonstring
  • matchCandidatesarray<object>Family-dedup MATCH result. Empty at cold-start is correct.
    • productIdstringrequired
    • titlestringrequired
    • confidencenumber · doublerequired
    • signalsarray<string>Signal type names that contributed (barcode, embedding, attribute, ...).
    • reasonstringGuard verdict reason when the relevance guard ran (<= 160 chars).
    • primaryImageUrlstring · uri
    • variantCountinteger
  • confidencesobjectPer-field grounding confidence (0.0 to 1.0).
  • aiAvailablebooleanrequiredWhether AI services were available during identification. Always present. False when the IDENTIFY / GROUND / MATCH AI legs degraded and the response was assembled from the surviving deterministic signals (barcode fast path, carried…

Errors

401 · 403 · 422 · 429 · 503 — See the error reference

httpRequest
POST /rest/v1/matching/identify
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "query": "Query",
  "barcodes": []
}
jsonResponse · 200
{
  "categoryId": "Category id",
  "categoryPath": [],
  "brandId": "Brand id",
  "brandName": "Brand name",
  "title": "Title",
  "description": "Description",
  "groundedAttributes": [],
  "variantOptions": [],
  "customOptions": [],
  "physical": {
    "weightGrams": 0,
    "lengthMm": 0,
    "widthMm": 0,
    "heightMm": 0
  },
  "priceBand": {
    "minCents": 129900,
    "maxCents": 129900,
    "suggestedCents": 129900,
    "currency": "EUR",
    "basis": "offers",
    "confidence": 0
  },
  "barcodes": [],
  "unresolved": [],
  "matchCandidates": [],
  "confidences": {},
  "aiAvailable": false
}
read#
POST/rest/v1/matching/match-productsproducts:readMatch products from marketplace catalog (v2 grounded shape preferred)

AI-first family-dedup product matching against the marketplace catalog. The request carries two coexisting shapes discriminated by field PRESENCE (no version header, no separate path): the v1 flat `intent` (the original `ProductIntent`…

Requires

products:read

Request body · application/json

  • intentobjectv1 flat intent. Optional; provide this OR `grounded` (at least one required).
    • titleHintstringProduct title hint from intent parsing.
    • brandHintstringBrand name hint.
    • categoryHintstringCategory name hint.
    • barcodestringBarcode for exact catalog lookup.
    • inferredAttributesobjectKey-value pairs of inferred attributes for matching.
    • queryTextstringOriginal free-text query for text similarity matching.
  • groundedobjectv2 canonical grounded identification (preferred). Optional; provide this OR `intent`. When both are present, `grounded` wins.
    • categoryIdstringResolved leaf category id, or null when unresolved.
    • categoryPatharray<string>
    • brandIdstringResolved brand id, or null when unresolved.
    • brandNamestring
    • titlestring
    • descriptionstring
    • groundedAttributesarray<object>
    • variantOptionsarray<object>
    • customOptionsarray<object>
    • physicalobjectPhysical dimensions in canonical integer units -- millimetres and grams. Every field is optional: grounding fills what it can validate and routes the rest to `unresolved`. Floats are deliberately disallowed to avoid rounding drift.
    • priceBandobjectAn offer-level price estimate in integer cents with an explicit derivation basis. `basis=offers` when the band is grounded in qualifying-offer aggregates of a matched family; `basis=model` when it is an LLM estimate carried with a…
    • barcodesarray<string>
    • unresolvedarray<object>Fields the grounding layer could not resolve, each carrying the model's proposed string (invariant 1).
    • matchCandidatesarray<object>Family-dedup MATCH result. Empty at cold-start is correct.
    • confidencesobjectPer-field grounding confidence (0.0 to 1.0).
  • sellerStoreIdstringSeller's store ID. Used to suppress the seller's own products from results.
  • modestringExecution mode.One of: interactive · batch · review
  • limitintegerMaximum number of candidates to return.
  • minConfidencenumber · doubleMinimum confidence threshold (0-100). Candidates below this are filtered.

Response · 200

  • candidatesarray<object>requiredRanked list of candidate products.
    • productIdstringrequiredMarketplace product identifier.
    • titlestringrequiredProduct display title.
    • confidencenumber · doublerequiredMatch confidence score (0-100). Only a barcode identity or an AI-confirmed relevance verdict reaches the "Strong" band (>= 75); a raw retrieval hit the LLM guard could not vet is capped below 75 (~65 max) and surfaces as a "possible" match.
    • sourcestringrequiredWhich catalog source produced this candidate.One of: seller_catalog · marketplace_catalog
    • reasonstringrequiredHuman-readable explanation of why this candidate matched.
    • suppressedBystringIf this candidate was suppressed by a higher-confidence match, the ID of the suppressing product.
    • variantCountintegerNumber of marketplace variants for this product.
    • primaryImageUrlstring · uriURL of the primary product image.
    • matchSignalsarray<object>Breakdown of individual signals that contributed to the score.
  • totalintegerrequiredTotal number of candidates (before limit).
  • aiAvailablebooleanrequiredWhether the AI relevance guard vetted the retrieved candidates. False when there was relevance evidence that could not be vetted (the guard was not injected, timed out, or failed) -- results then come from capped raw retrieval only. True…

Errors

401 · 403 · 422 · 503 — See the error reference

httpRequest
POST /rest/v1/matching/match-products
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "intent": {
    "titleHint": "Title hint",
    "brandHint": "Brand hint",
    "categoryHint": "Category hint",
    "barcode": "Barcode",
    "inferredAttributes": {},
    "queryText": "Query text"
  },
  "grounded": {
    "categoryId": "Category id",
    "categoryPath": [],
    "brandId": "Brand id",
    "brandName": "Brand name",
    "title": "Title",
    "description": "Description",
    "groundedAttributes": [],
    "variantOptions": [],
    "customOptions": [],
    "physical": {
      "weightGrams": 0,
      "lengthMm": 0,
      "widthMm": 0,
      "heightMm": 0
    },
    "priceBand": {
      "minCents": 129900,
      "maxCents": 129900,
      "suggestedCents": 129900,
      "currency": "EUR",
      "basis": "offers",
      "confidence": 0
    },
    "barcodes": [],
    "unresolved": [],
    "matchCandidates": [],
    "confidences": {}
  },
  "sellerStoreId": "Seller store id",
  "mode": "interactive",
  "limit": 10,
  "minConfidence": 50
}
jsonResponse · 200
{
  "candidates": [
    {
      "productId": "Product id",
      "title": "Title",
      "confidence": 0,
      "source": "seller_catalog",
      "reason": "Reason",
      "suppressedBy": "Suppressed by",
      "variantCount": 0,
      "primaryImageUrl": "https://api.example.com",
      "matchSignals": []
    }
  ],
  "total": 129900,
  "aiAvailable": false
}
read#
POST/rest/v1/matching/suggest-variantsproducts:readSuggest variant candidates

Returns ranked variant candidates from existing marketplace variants and AI-proposed variants. Requires product context and category to determine variant-defining attributes. Also returns suggested option axes for the category.

Requires

products:read

Request body · application/json

  • productIdstringrequiredMarketplace product ID to suggest variants for.
  • intentobjectParsed intent attributes for context-aware variant suggestion (e.g., {"color": "Black", "size": "42"}).
  • categoryIdstringrequiredCategory ID for determining variant-defining attributes.

Response · 200

  • variantsarray<object>requiredRanked variant candidates.
    • optionValuesobjectrequiredOption value mapping for this variant (e.g., {"Size": "42", "Color": "Black"}).
    • sourcestringrequiredWhether this variant exists in the marketplace catalog or was proposed by AI.One of: marketplace_variant · ai_proposed
    • confidencenumber · doublerequiredVariant match confidence (0-100).
    • reasonstringrequiredHuman-readable explanation for the suggestion.
    • marketplaceVariantIdstringMarketplace variant ID (present for marketplace_variant source, null for ai_proposed).
    • parsedIntentMatchbooleanWhether this variant matches the seller's parsed intent.
  • suggestedOptionsarray<object>requiredSuggested variant option axes for the category.
    • namestringrequiredOption axis name (e.g., Size, Color).
    • confidencenumber · doublerequiredConfidence that this is a variant-defining axis (0.0 to 1.0).
    • sellerValuestringSeller's extracted value for this option axis. Present when AI infers attribute values from seller input (e.g., "42" for Size). Null for cache-sourced options from taxonomy.
  • aiAvailablebooleanrequiredWhether AI services were available during suggestion.

Errors

401 · 403 · 422 · 503 — See the error reference

httpRequest
POST /rest/v1/matching/suggest-variants
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "productId": "Product id",
  "intent": {},
  "categoryId": "Category id"
}
jsonResponse · 200
{
  "variants": [
    {
      "optionValues": {},
      "source": "marketplace_variant",
      "confidence": 0,
      "reason": "Reason",
      "marketplaceVariantId": "Marketplace variant id",
      "parsedIntentMatch": false
    }
  ],
  "suggestedOptions": [
    {
      "name": "Name",
      "confidence": 0,
      "sellerValue": "Seller value"
    }
  ],
  "aiAvailable": false
}
read#
POST/rest/v1/matching/match-variantsproducts:readMatch listing variant against marketplace product variants

Compares a listing variant's option values against all variants of a marketplace product. Returns ranked matches scored by per-option-value similarity. Review mode includes pending_review and in_review variants.

Requires

products:read

Request body · application/json

  • listingVariantOptionValuesobjectrequiredThe listing variant's option values to match (e.g., {"Size": "42", "Color": "Black"}).
  • marketplaceProductIdstringrequiredMarketplace product ID to match variants against.
  • modestringExecution mode. Review mode includes pending_review and in_review variants in the match pool.One of: interactive · batch · review

Response · 200

  • matchesarray<object>requiredRanked marketplace variant matches.
    • marketplaceVariantIdstringrequiredMatched marketplace variant identifier.
    • optionValuesobjectrequiredOption values of the matched marketplace variant.
    • confidencenumber · doublerequiredOverall match confidence (0-100).
    • reasonstringrequiredHuman-readable explanation of the match.
    • optionValueMatchesarray<object>Per-option-value similarity breakdown.
  • aiAvailablebooleanrequiredWhether AI services were available during matching.

Errors

401 · 403 · 422 · 503 — See the error reference

httpRequest
POST /rest/v1/matching/match-variants
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "listingVariantOptionValues": {},
  "marketplaceProductId": "Marketplace product id",
  "mode": "interactive"
}
jsonResponse · 200
{
  "matches": [
    {
      "marketplaceVariantId": "Marketplace variant id",
      "optionValues": {},
      "confidence": 0,
      "reason": "Reason",
      "optionValueMatches": []
    }
  ],
  "aiAvailable": false
}
read#
POST/rest/v1/matching/product-detailproducts:readGet full marketplace product detail for wizard prefill

Returns the full marketplace product detail for a known product id so the seller listing wizard can pre-populate its fields. Looks up the product in the marketplace catalog projection and returns its title, description, brand, category…

Requires

products:read

Request body · application/json

  • productIdstringrequiredMarketplace product ID to fetch full detail for.

Response · 200

  • productIdstringrequiredMarketplace product identifier.
  • titlestringrequiredProduct display title.
  • descriptionstringProduct description.
  • brandstringBrand display NAME -- the canonical registry name when brandId is a servable brand, else the EAV brand-attribute fallback.
  • brandIdstringCanonical marketplace brand identifier, emitted only when the product's brandId resolves to a servable (non-suspended) brand in the local read model -- the wizard prefills its brand picker from it. Null when the product carries no brand or…
  • categoryIdstringAssigned category identifier.
  • categoryPatharray<string>Full taxonomy path from root to the product's category.
  • attributesobjectProduct attributes keyed by the stable attribute handle, each mapping to the list of resolved value names. This handle-keyed, list-valued shape is what the seller wizard maps onto its category-attribute chips for "Use as template"…
  • optionsarray<object>Variant-defining option axes with their values.
    • namestringrequiredOption axis name (e.g., Size, Color).
    • valuesarray<string>Available values for this option axis.
  • variantsarray<object>Existing marketplace variants of the product.
    • idstringrequiredMarketplace variant identifier.
    • optionValuesobjectOption value mapping (e.g., {"Size": "42", "Color": "Black"}).
    • skustringStock-keeping unit code.
  • mediaarray<string>Product media URLs.

Errors

401 · 403 · 404 · 503 — See the error reference

httpRequest
POST /rest/v1/matching/product-detail
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "productId": "Product id"
}
jsonResponse · 200
{
  "productId": "Product id",
  "title": "Title",
  "description": "Description",
  "brand": "Brand",
  "brandId": "Brand id",
  "categoryId": "Category id",
  "categoryPath": [],
  "attributes": {},
  "options": [],
  "variants": [],
  "media": []
}
read#

Governance 2 operations

POST/rest/v1/governance/match-productspublicEvaluate listing for product matching

Accepts a listing snapshot and returns a matching verdict with per-variant decisions. Used by the publication review pipeline to determine whether the listing maps to an existing product or requires new product creation. Internal…

Requires

public

Request body · application/json

  • snapshotobjectrequiredListing data snapshot submitted for governance review. Contains all fields needed by the AI matching and review services to evaluate a listing before publication.
    • titlestringrequiredListing title.
    • descriptionstringListing description text.
    • categoryIdstringCategory identifier for the listing.
    • variantsarray<object>Listing variants included in the snapshot.
    • optionsarray<object>Option axis definitions for the listing.
    • attributesarray<object>Product attributes for the listing.
    • mediaarray<object>Media entries for the listing.

Response · 200

  • verdictstringrequiredPer-dimension verdict for content, category, and price assessments, and the overall verdict of the standalone match-products endpoint. Aligned with the PHP `VerdictOutcome` enum.One of: pass · flag · error
  • certaintyintegerrequiredOverall certainty of the verdict (0-100).
  • severitystringrequiredFive-level severity, aligned with the PHP `ContentSeverity` enum. `critical` is reserved for absolute content prohibitions; `none` marks a clean, passing assessment.One of: critical · high · medium · low · none
  • reasoningstringrequiredHuman-readable explanation of the matching decision.
  • productMatchobjectrequiredBest-match product from the marketplace catalog, if any.
    • productIdstringMatched product identifier.
    • productTitlestringMatched product title.
    • confidencenumber · doubleMatch confidence score (0-100).
  • variantResultsarray<object>requiredPer-variant matching decisions.
    • listingVariantIdstringrequiredIdentifier of the listing variant that was evaluated.
    • decisionstringrequiredThe six matching routing decisions produced per listing variant. Aligned with the PHP `MatchingDecision` enum.One of: auto_match_existing_variant · auto_create_variant · auto_create_both · hold_with_product_candidates · hold_with_variant_candidates · auto_create_variant_incomplete
    • confidencenumber · doublerequiredDecision confidence score (0-100).
    • matchedProductIdstringExisting canonical Product this listing variant's decision attaches to. Set only for the family-attaching decisions; null for `auto_create_both` and the `hold_*` outcomes. The resolve-time reconciler uses it to classify divergence against…
    • matchedVariantIdstringMarketplace variant ID this listing variant was matched to.
    • candidatesarray<object>Candidate variant matches considered during evaluation.
  • aiMetadataobjectMetadata about the matching engine that produced the verdict.
    • modelstringMatching engine identifier.
    • versionstringMatching engine version.
    • processingTimeMsintegerProcessing time in milliseconds.

Errors

422 — See the error reference

httpRequest
POST /rest/v1/governance/match-products
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "snapshot": {
    "title": "Title",
    "description": "Description",
    "categoryId": "Category id",
    "variants": [],
    "options": [],
    "attributes": [],
    "media": []
  }
}
jsonResponse · 200
{
  "verdict": "pass",
  "certainty": 0,
  "severity": "critical",
  "reasoning": "Reasoning",
  "productMatch": {
    "productId": "Product id",
    "productTitle": "Product title",
    "confidence": 0
  },
  "variantResults": [
    {
      "listingVariantId": "Listing variant id",
      "decision": "auto_match_existing_variant",
      "confidence": 0,
      "matchedProductId": "Matched product id",
      "matchedVariantId": "Matched variant id",
      "candidates": []
    }
  ],
  "aiMetadata": {
    "model": "governance-match",
    "version": "1.0.0",
    "processingTimeMs": 0
  }
}
write#
POST/rest/v1/governance/reviewpublicPer-variant publication review (content, category, price, matching)

Accepts a listing snapshot and returns, for every listing variant, four AI assessments: content policy, category fit, price fit, and matching. Used by the svc-marketplace Governance module to auto-approve clean variants and escalate the…

Requires

public

Request body · application/json

  • snapshotobjectrequiredListing data snapshot submitted for governance review. Contains all fields needed by the AI matching and review services to evaluate a listing before publication.
    • titlestringrequiredListing title.
    • descriptionstringListing description text.
    • categoryIdstringCategory identifier for the listing.
    • variantsarray<object>Listing variants included in the snapshot.
    • optionsarray<object>Option axis definitions for the listing.
    • attributesarray<object>Product attributes for the listing.
    • mediaarray<object>Media entries for the listing.

Response · 200

  • variantsarray<object>requiredPer-variant assessments, one entry per listing variant.
    • listingVariantIdstringrequiredIdentifier of the listing variant that was evaluated.
    • contentobjectrequiredContent-policy verdict for a single listing variant.
    • categoryobjectrequiredCategory-fit verdict for a single listing variant.
    • priceobjectrequiredPrice-fit verdict for a single listing variant.
    • matchingobjectrequiredPer-variant matching outcome: one of six routing decisions plus candidate references.
  • aiMetadataobjectMetadata about the model that produced the review.
    • modelstringReview engine identifier.
    • promptVersionstringPrompt/version identifier for the review model.
    • processingTimeMsintegerProcessing time in milliseconds.

Errors

422 — See the error reference

httpRequest
POST /rest/v1/governance/review
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "snapshot": {
    "title": "Title",
    "description": "Description",
    "categoryId": "Category id",
    "variants": [],
    "options": [],
    "attributes": [],
    "media": []
  }
}
jsonResponse · 200
{
  "variants": [
    {
      "listingVariantId": "Listing variant id",
      "content": {
        "verdict": "pass",
        "certainty": 0,
        "severity": "critical",
        "reasoning": "Reasoning",
        "details": {
          "categories": []
        }
      },
      "category": {
        "verdict": "pass",
        "certainty": 0,
        "severity": "critical",
        "reasoning": "Reasoning",
        "details": {
          "suppliedCategoryId": "Supplied category id"
        }
      },
      "price": {
        "verdict": "pass",
        "certainty": 0,
        "severity": "critical",
        "reasoning": "Reasoning",
        "details": {
          "referencePriceAmount": 129900,
          "lowerBound": 0,
          "upperBound": 0,
          "deltaPct": 0,
          "baselineSource": "offers",
          "offerCount": 0
        }
      },
      "matching": {
        "decision": "auto_match_existing_variant",
        "confidence": 0,
        "productMatch": {
          "productId": "Product id",
          "productTitle": "Product title",
          "confidence": 0
        },
        "matchedVariantId": "Matched variant id",
        "candidates": []
      }
    }
  ],
  "aiMetadata": {
    "model": "governance-matcher",
    "promptVersion": "governance-review-1.0.0",
    "processingTimeMs": 0
  }
}
write#

Handshake API

Seller CMS Connections 4 operations

GET/rest/v1/seller/cms-connections/{storeId}products:readGet the store's CMS connection

Returns the CMS connection for the authenticated seller's store as a list of 0–1 items. A store the seller does not own, or one with no connection, returns `{ "items": [] }`. Requires the `products:read` capability (the Products area at…

Requires

products:read

Path parameters

  • storeIdstring · uuidrequiredStore identifier (UUID).

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequired
    • statusstringrequiredOne of: pending · active · suspended · disconnected
    • apiKeystringrequiredLive plugin API key. On GET it is an empty string unless the caller is the account owner or holds the Administrator role for this store; the ensure response always carries it.
    • apiSecretstringrequiredLive plugin signing secret. On GET it is an empty string unless the caller is the account owner or holds the Administrator role for this store; the ensure response always carries it.
    • platformstringrequiredOne of: unconfigured · woocommerce · shopify
    • connectedAtstring · date-time
    • lastActivitystring · date-time

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/cms-connections/01914d0e-8192-73a4-b5b6-213243546578
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-92a3-74b5-86c7-324354657689",
      "status": "pending",
      "apiKey": "mk_live_a1b2c3d4e5f6...",
      "apiSecret": "ms_live_a1b2c3d4e5f6...",
      "platform": "unconfigured",
      "connectedAt": "2026-09-10T09:24:11Z",
      "lastActivity": "2026-09-10T09:24:11Z"
    }
  ]
}
read#
POST/rest/v1/seller/cms-connections/{storeId}administratorEnsure the store's CMS connection

Ensures the authenticated seller's store has a CMS connection with generated `mk_live_`/`ms_live_` credentials and returns it. Idempotent: an existing connection is returned UNCHANGED (credentials are never regenerated), always as `201…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore identifier (UUID).

Response · 201

  • idstring · uuidrequired
  • statusstringrequiredOne of: pending · active · suspended · disconnected
  • apiKeystringrequiredLive plugin API key. On GET it is an empty string unless the caller is the account owner or holds the Administrator role for this store; the ensure response always carries it.
  • apiSecretstringrequiredLive plugin signing secret. On GET it is an empty string unless the caller is the account owner or holds the Administrator role for this store; the ensure response always carries it.
  • platformstringrequiredOne of: unconfigured · woocommerce · shopify
  • connectedAtstring · date-time
  • lastActivitystring · date-time

Errors

401 · 403 · 404 · 500 · 502 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/cms-connections/01914d0e-8192-73a4-b5b6-213243546578
Authorization: Bearer $TOKEN
jsonResponse · 201
{
  "id": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "status": "pending",
  "apiKey": "mk_live_a1b2c3d4e5f6...",
  "apiSecret": "ms_live_a1b2c3d4e5f6...",
  "platform": "unconfigured",
  "connectedAt": "2026-09-10T09:24:11Z",
  "lastActivity": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/cms-connections/{storeId}/{connectionId}products:readGet CMS connection

Returns a specific CMS connection for the authenticated seller. Requires the `products:read` capability (the Products area at read level). `apiKey` and `apiSecret` are empty strings unless the caller is the account owner or holds the…

Requires

products:read

Path parameters

  • storeIdstring · uuidrequiredStore identifier (UUID).
  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Response · 200

  • idstring · uuidrequired
  • storeIdstring · uuidrequired
  • userIdstringrequired
  • platformstringrequiredOne of: woocommerce · shopify
  • siteUrlstringrequired
  • statusstringrequiredOne of: pending · active · suspended · disconnected
  • pluginVersionstring
  • apiKeystringrequiredLive plugin API key; an empty string unless the caller is the account owner or holds the Administrator role for this store.
  • apiSecretstringrequiredLive plugin signing secret; an empty string unless the caller is the account owner or holds the Administrator role for this store.
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/cms-connections/01914d0e-4d5e-7f60-b172-8d9e0f102134/01914d0e-92a3-74b5-86c7-324354657689
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-5e6f-7071-8283-9e0f10213245",
  "storeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "userId": "User id",
  "platform": "woocommerce",
  "siteUrl": "https://shop.example.com",
  "status": "pending",
  "pluginVersion": "1.2.0",
  "apiKey": "mk_live_a1b2c3d4e5f6...",
  "apiSecret": "ms_live_a1b2c3d4e5f6...",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#
POST/rest/v1/seller/cms-connections/{storeId}/{connectionId}/regenerate-credentialsadministratorRegenerate CMS connection credentials

Regenerates the API key and secret for the specified CMS connection, invalidating the previous credentials. The seller copies the new credentials into the plugin to reconnect. Restricted to the account owner or a member holding the…

Requires

administrator

Path parameters

  • storeIdstring · uuidrequiredStore identifier (UUID).
  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Response · 200

  • apiKeystringrequired
  • apiSecretstringrequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/cms-connections/01914d0e-a3b4-75c6-97d8-43546576879a/01914d0e-b4c5-76d7-a8e9-546576879aab/regenerate-credentials
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "apiKey": "mk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "apiSecret": "ms_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
}
write#

Seller CMS Sync 3 operations

POST/rest/v1/seller/cms-connections/{storeId}/{connectionId}/importproducts:read_writeStart CMS import

Triggers an initial full import from the CMS for the specified connection. Requires the `products:read_write` capability (the Products area at read-write level).

Requires

products:read_write

Path parameters

  • storeIdstring · uuidrequiredStore identifier (UUID).
  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Response · 201

  • idstring · uuidrequired
  • connectionIdstring · uuidrequired
  • kindstringrequiredOne of: full_sync · incremental · reverse_sync
  • statusstringrequiredOne of: pending · running · completed · failed
  • totalintegerrequired
  • succeededintegerrequired
  • failedintegerrequired
  • flowIdstring · uuid
  • failureReasonstringWhy the sync job failed, as a reason code the client words for the seller. Null unless the status is failed.One of: sync_not_started · sync_interrupted
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
POST /rest/v1/seller/cms-connections/01914d0e-6f70-7182-9394-0f1021324356/01914d0e-b4c5-76d7-a8e9-546576879aab/import
Authorization: Bearer $TOKEN
jsonResponse · 201
{
  "id": "01914d0e-7081-7293-a4a5-102132435467",
  "connectionId": "01914d0e-b4c5-76d7-a8e9-546576879aab",
  "kind": "full_sync",
  "status": "pending",
  "total": 120,
  "succeeded": 115,
  "failed": 5,
  "flowId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023",
  "failureReason": "sync_not_started",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
GET/rest/v1/seller/cms-connections/{storeId}/{connectionId}/sync-jobsproducts:readList sync jobs for a connection

Returns all sync jobs for a given CMS connection. Used by the seller dashboard for polling sync progress. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequiredStore identifier (UUID).
  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequired
    • connectionIdstring · uuidrequired
    • kindstringrequiredOne of: full_sync · incremental · reverse_sync
    • statusstringrequiredOne of: pending · running · completed · failed
    • totalintegerrequired
    • succeededintegerrequired
    • failedintegerrequired
    • flowIdstring · uuid
    • failureReasonstringWhy the sync job failed, as a reason code the client words for the seller. Null unless the status is failed.One of: sync_not_started · sync_interrupted
    • createdAtstring · date-timerequired
    • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/cms-connections/01914d0e-b4c5-76d7-a8e9-546576879aab/01914d0e-8192-73a4-b5b6-213243546578/sync-jobs
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-2b3c-7d4e-9f50-6b7c8d9e0f12",
      "connectionId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "kind": "full_sync",
      "status": "pending",
      "total": 120,
      "succeeded": 115,
      "failed": 5,
      "flowId": "01914d0e-a3b4-75c6-97d8-43546576879a",
      "failureReason": "sync_not_started",
      "createdAt": "2026-09-10T09:24:11Z",
      "updatedAt": "2026-09-10T09:24:11Z"
    }
  ]
}
read#
GET/rest/v1/seller/cms-connections/{storeId}/{connectionId}/sync-jobs/{jobId}products:readGet sync job status

Returns the status and progress of a specific sync job. Requires the `products:read` capability (the Products area at read level).

Requires

products:read

Path parameters

  • storeIdstring · uuidrequiredStore identifier (UUID).
  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).
  • jobIdstring · uuidrequiredSync job identifier.

Response · 200

  • idstring · uuidrequired
  • connectionIdstring · uuidrequired
  • kindstringrequiredOne of: full_sync · incremental · reverse_sync
  • statusstringrequiredOne of: pending · running · completed · failed
  • totalintegerrequired
  • succeededintegerrequired
  • failedintegerrequired
  • flowIdstring · uuid
  • failureReasonstringWhy the sync job failed, as a reason code the client words for the seller. Null unless the status is failed.One of: sync_not_started · sync_interrupted
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 403 · 404 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/cms-connections/01914d0e-a3b4-75c6-97d8-43546576879a/01914d0e-b4c5-76d7-a8e9-546576879aab/sync-jobs/01914d0e-c5d6-77e8-b9fa-6576879aabbc
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "id": "01914d0e-92a3-74b5-86c7-324354657689",
  "connectionId": "01914d0e-92a3-74b5-86c7-324354657689",
  "kind": "full_sync",
  "status": "pending",
  "total": 120,
  "succeeded": 115,
  "failed": 5,
  "flowId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "failureReason": "sync_not_started",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
read#

Plugin 5 operations

GET/rest/v1/connections/testauthenticatedResolve the plugin connection from its API key

Called by the CMS plugin to discover its connection identity from a `Bearer mk_live_…` API key. The plugin does not yet know its `connectionId`, so the key is the only credential. Resolves identity only — works while the connection is…

Requires

authenticated

Response · 200

  • connectionIdstring · uuidrequired
  • storeIdstring · uuidrequired
  • statusstringrequiredOne of: pending · active · suspended · disconnected

Errors

401 · 500 — See the error reference

httpRequest
GET /rest/v1/connections/test
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "connectionId": "01914d0e-92a3-74b5-86c7-324354657689",
  "storeId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
  "status": "pending"
}
read#
POST/rest/v1/connections/{connectionId}/registerauthenticatedRegister CMS plugin connection

Called by the CMS plugin during the initial handshake to bind the connection to a platform + site URL and activate it (`pending` → `active`).

Requires

authenticated

Path parameters

  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Request body · application/json

  • platformstringrequiredCMS platform the plugin runs on.One of: woocommerce · shopify
  • siteUrlstringrequiredBase URL of the CMS storefront: https:// on port 443, a public DNS name or public IP, an optional path of letters, digits and ".", "_", "~", "-", and no credentials, query or fragment. Anything else is refused with 422 (code…
  • pluginVersionstringPlugin version installed on the CMS.

Response · 200

  • connectionIdstring · uuidrequired
  • storeIdstring · uuidrequired
  • platformstringrequiredOne of: woocommerce · shopify
  • siteUrlstringrequired
  • statusstringrequiredOne of: pending · active · suspended · disconnected
  • pluginVersionstring

Errors

400 · 401 · 404 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/connections/01914d0e-8192-73a4-b5b6-213243546578/register
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "platform": "woocommerce",
  "siteUrl": "https://shop.example.com",
  "pluginVersion": "1.2.0"
}
jsonResponse · 200
{
  "connectionId": "01914d0e-6f70-7182-9394-0f1021324356",
  "storeId": "01914d0e-92a3-74b5-86c7-324354657689",
  "platform": "woocommerce",
  "siteUrl": "https://shop.example.com",
  "status": "pending",
  "pluginVersion": "1.2.0"
}
write#
POST/rest/v1/connections/{connectionId}/syncauthenticatedTrigger sync from plugin

Triggers an import from the CMS plugin side. With no body (or an empty one) a full catalog backfill runs; pass `productIds` to scope the sync to specific products (single "Sync Now" or a bulk selection). On successful completion the synced…

Requires

authenticated

Path parameters

  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Request body · application/json

  • productIdsarray<integer>CMS-native product ids to scope the sync to. Each id must be a positive integer. Omit for a full catalog backfill.

Response · 201

  • idstring · uuidrequired
  • connectionIdstring · uuidrequired
  • kindstringrequiredOne of: full_sync · incremental · reverse_sync
  • statusstringrequiredOne of: pending · running · completed · failed
  • totalintegerrequired
  • succeededintegerrequired
  • failedintegerrequired
  • flowIdstring · uuid
  • failureReasonstringWhy the sync job failed, as a reason code the client words for the seller. Null unless the status is failed.One of: sync_not_started · sync_interrupted
  • createdAtstring · date-timerequired
  • updatedAtstring · date-timerequired

Errors

401 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/connections/01914d0e-a3b4-75c6-97d8-43546576879a/sync
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "productIds": [
    1042,
    1043
  ]
}
jsonResponse · 201
{
  "id": "01914d0e-8192-73a4-b5b6-213243546578",
  "connectionId": "01914d0e-8192-73a4-b5b6-213243546578",
  "kind": "full_sync",
  "status": "pending",
  "total": 120,
  "succeeded": 115,
  "failed": 5,
  "flowId": "01914d0e-8192-73a4-b5b6-213243546578",
  "failureReason": "sync_not_started",
  "createdAt": "2026-09-10T09:24:11Z",
  "updatedAt": "2026-09-10T09:24:11Z"
}
write#
PUT/rest/v1/connections/{connectionId}/settingsauthenticatedChange the plugin connection sync settings

Called by the CMS plugin when the seller saves its sync settings, and after the connection is registered. `priceStockSync` = `false` stops svc-handshake from pushing marketplace stock changes to the CMS; a connection that never sent it…

Requires

authenticated

Path parameters

  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Request body · application/json

  • priceStockSyncbooleanrequiredWhether svc-handshake pushes marketplace stock changes to the CMS.

Response · 200

  • priceStockSyncbooleanrequired

Errors

400 · 401 · 404 · 422 · 500 — See the error reference

httpRequest
PUT /rest/v1/connections/01914d0e-8192-73a4-b5b6-213243546578/settings
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "priceStockSync": true
}
jsonResponse · 200
{
  "priceStockSync": true
}
write#
POST/rest/v1/webhooks/{connectionId}/product-updatedauthenticatedReceive a CMS product-updated webhook

Notifies svc-handshake that a product changed in the source CMS. Idempotent on `eventId`; records a receipt and emits an internal `WebhookReceived` signal. Does not trigger a full re-import.

Requires

authenticated

Path parameters

  • connectionIdstring · uuidrequiredCMS connection identifier (UUID).

Request body · application/json

  • externalProductIdstringrequiredIdentifier of the product in the source CMS.
  • eventTypestringrequiredSource CMS classification of the change.
  • eventIdstringrequiredIdempotency key — unique per webhook delivery.
  • changedFieldsarray<string>Names of the product fields that changed.
  • stockLevelsarray<object>Current managed stock of the product: one entry with a null `externalVariantId` for a simple product, one entry per variation for a variable product, and none unless every variation manages its own stock. When `changedFields` holds only…
    • externalVariantIdstringIdentifier of the variation in the source CMS; null for a simple product.
    • stockQuantityintegerrequiredCurrent managed stock quantity of the product or variation in the source CMS.

Response · 202

  • eventIdstringrequired
  • outcomestringrequiredOne of: processed · duplicate · ignored · failed

Errors

401 · 422 · 500 — See the error reference

httpRequest
POST /rest/v1/webhooks/01914d0e-92a3-74b5-86c7-324354657689/product-updated
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "externalProductId": "wc-1042",
  "eventType": "product.updated",
  "eventId": "5f3c2b1a-7d4e-4c8a-9b1f-2e3d4c5b6a7f",
  "changedFields": [
    "price",
    "stock_quantity"
  ],
  "stockLevels": [
    {
      "externalVariantId": "1043",
      "stockQuantity": 7
    }
  ]
}
jsonResponse · 202
{
  "eventId": "5f3c2b1a-7d4e-4c8a-9b1f-2e3d4c5b6a7f",
  "outcome": "processed"
}
write#

Chronicle API

Seller Activity 1 operation

GET/rest/v1/seller/accounts/{accountId}/activityactivity:readSeller activity feed

Returns the activity feed (newest first, cursor-paginated) of the account named in the `{accountId}` path segment -- the caller's own account, or one they are a member of. Scoped to the requester's membership: the account owner and…

Requires

activity:read

Path parameters

  • accountIdstringrequiredThe account (owner UserId) whose feed to read. Verified against the caller's membership.

Query parameters

  • afterstring · uuidCursor for forward pagination (ledger row id of the last item on the previous page)
  • beforestring · uuidCursor for backward pagination (ledger row id of the first item on the previous page)
  • limitintegerNumber of items per page
  • includeTotalCountbooleanOpt in to `_metadata.totalCount` — an extra COUNT query over the same filters. Off by default (cursor pagination needs no total); set `true` when a range label like "1–20 of 137" is wanted.
  • actorIdstringFilter by the acting principal's opaque id
  • actorKindstringFilter by the acting principal's kindOne of: customer · seller · admin · agent · system · payment_webhook
  • typestringExact CloudEvents type (e.g. `order.order_created`)
  • typePrefixstringCloudEvents type prefix (e.g. `order.`)
  • objectTypestringFilter by primary subject kindOne of: order · store_payment_provider · listing · store · membership · role · invitation · shipping_method · location · distribution_options · locker_method · stock_item
  • objectIdstringFilter by primary subject id
  • outcomestringFilter by outcomeOne of: succeeded · denied · failed
  • correlationIdstring · uuidCorrelation id — matches the request trace id OR the saga flow id
  • occurredFromstring · date-timeLower bound (inclusive) on event time, ISO 8601
  • occurredTostring · date-timeUpper bound on event time, ISO 8601, inclusive of the whole second it names (…T23:59:59Z and …T23:59:59.5Z both include events up to 23:59:59.999999)

Response · 200

  • itemsarray<object>required
    • idstring · uuidrequiredLedger row id (UUIDv7) -- also the feed cursor
    • occurredAtstring · date-timerequiredEvent time from the publisher (ISO 8601)
    • recordedAtstring · date-timerequiredServer-authoritative receipt time (ISO 8601)
    • sourcestringrequiredOriginating service (e.g. `svc-purchase`)
    • typestringrequiredCloudEvents type (prefix-filterable)
    • outcomestringrequiredThe outcome of the recorded act.One of: succeeded · denied · failed
    • denyReasonstringSet only when `outcome` is `denied`. One of `suspended`, `insufficient_capability`, `out_of_scope`, `administrator_only`, `not_member`.
    • actorobjectrequiredWho performed (or was denied) the act.
    • accountobjectThe account the record is scoped to (null when not account-scoped).
    • storeobjectThe store the record is scoped to (null for account-level records).
    • objectobjectThe primary subject the record is about (null when the event maps to no subject).
    • contextobjectWhitelisted, structured-scalar bag (status transitions, capability area/level, classification codes, counts). Never free text or PII.
    • correlationIdstring · uuidSaga flow id (the second correlation axis)
    • traceIdstring · uuidrequiredRequest trace id
  • _metadataobjectrequired
    • limitintegerrequired
    • hasMorebooleanrequired
    • nextCursorstring · uuid
    • prevCursorstring · uuid
    • totalCountintegerOnly present when includeTotalCount=true

Errors

401 · 403 · 404 · 422 · 500 · 503 — See the error reference

httpRequest
GET /rest/v1/seller/accounts/Account id/activity
Authorization: Bearer $TOKEN
jsonResponse · 200
{
  "items": [
    {
      "id": "01914d0e-8192-73a4-b5b6-213243546578",
      "occurredAt": "2026-09-10T09:24:11Z",
      "recordedAt": "2026-09-10T09:24:11Z",
      "source": "svc-purchase",
      "type": "order.order_shipment_advanced",
      "outcome": "succeeded",
      "denyReason": null,
      "actor": {
        "kind": "customer",
        "id": "Id",
        "displayName": "Display name",
        "credentialType": "Credential type",
        "onBehalfOf": {
          "kind": "customer",
          "id": "Id",
          "displayName": "Display name"
        }
      },
      "account": {
        "id": "Id"
      },
      "store": {
        "id": "Id"
      },
      "object": {
        "type": "order",
        "id": "Id"
      },
      "context": {
        "from": "packed",
        "to": "shipped"
      },
      "correlationId": "01914d0e-4d5e-7f60-b172-8d9e0f102134",
      "traceId": "01914d0e-3c4d-7e5f-a061-7c8d9e0f1023"
    }
  ],
  "_metadata": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "01914d0e-a3b4-75c6-97d8-43546576879a",
    "prevCursor": "01914d0e-a3b4-75c6-97d8-43546576879a",
    "totalCount": 129900
  }
}
read#

Errors

Every error is an RFC 7807 problem document with type, title, status and a human-readable detail. Validation errors add an errors list naming each field.

StatusWhenWhat to do
401Missing or expired tokenRequest a new token and retry
403The role — or, for a delegated agent, the grant — does not reach this action or store; reason names whichAsk an administrator to widen the role, or widen the grant on the Agents page
404Unknown store, product or order — or a store you cannot seeCheck the id and the store scope
422Validation failedRead errors; fix the fields named
409The action conflicts with the current state (e.g. publishing an archived variant)Read the current state and choose a valid transition
503Access could not be verified — the request fails closed, and nothing was changedRetry shortly with the same request
jsonExample · 422 validation-failed
{
  "type": "/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The request contains 1 validation error",
  "instance": "/rest/v1/seller/stores",
  "errors": [
    {
      "field": "title",
      "code": "not_blank",
      "message": "Title cannot be empty"
    }
  ],
  "traceId": "01914d0e-1a2b-7c3d-8e4f-5a6b7c8d9e01"
}