ecomone developers
Open Ecomone
Docs / API reference / Products

Products

Product catalog (read-only over REST).

List products#

GET/api/public/v1/productsproducts:read

List products, newest first. Lists products of the shop including archived ones (no archived filter).

Query parameters

limitinteger

Page size. Clamped to 1..200. Non-numeric values fall back to the default. Default: 50.

cursorstring (ISO 8601 timestamp)

Value of next_cursor from the previous page. Returns items with created_at strictly before this timestamp.

active"true" | "false"

Filter by active flag. Other values are ignored.

handlestring

Exact handle.

searchstring

Case-insensitive substring match on title.

shop_iduuid

Only for OAuth tokens that cover several shops: the shop to query. Must be one of the token's shops (else 403 forbidden). Required when the token covers more than one shop (else 400 shop_required). Optional for API keys (a key belongs to exactly one shop; any other value returns 403).

Response fields

dataarray

Items of this page.

next_cursorstring|null

created_at of the last item when more items exist, otherwise null.

data[].iduuid

Product id.

data[].handlestring

URL handle (also accepted as :id on the detail endpoint).

data[].titlestring

Product title.

data[].descriptionstring|null

Product description (HTML/text as stored).

data[].price_centsinteger

Price in minor units of the shop currency.

data[].compare_price_centsinteger|null

Compare-at (strike-through) price.

data[].cogs_centsinteger|null

Cost of goods per unit as entered by the merchant.

data[].imagesarray (raw JSON)

Product images as stored.

data[].stockinteger|null

Stock level (product level).

data[].activeboolean

Whether the product is active/visible.

data[].product_typestring|null

Product type (e.g. physical/digital) as stored.

data[].optionsarray (raw JSON)

Option definitions as stored.

data[].variantsarray (raw JSON)

Variants as stored.

data[].skustring|null

SKU.

data[].barcodestring|null

Barcode (EAN/GTIN).

data[].categorystring|null

Category.

data[].vendorstring|null

Vendor/manufacturer.

data[].tagsarray|null

Tags.

data[].archived_attimestamp|null

Set when the product is archived.

data[].created_attimestamp

Creation time; pagination key.

data[].updated_attimestamp

Last update.

Errors

401unauthorized

Any endpoint. Response carries header WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource".

403forbidden

Scope check per endpoint (and per body field on PATCH /orders/:id).

403forbidden

shop_id query parameter names a shop outside the credential's reach.

400shop_required

Multi-shop OAuth token without shop_id.

404not_found

Any endpoint when the resolved shop has active=false.

429rate_limited

Any endpoint. Header Retry-After (seconds until the next minute bucket).

500server_error

Any endpoint.

Try itNot authorized
Request
curl "https://api.ecomone.shop/api/public/v1/products?limit=10" \
  -H "X-Api-Key: $ECOMONE_API_KEY" \
  -H "X-Api-Secret: $ECOMONE_API_SECRET"
200Response
{
  "data": [
    {
      "id": "3b8b1f0a-1d2c-4f34-8a7c-6e2f9b4d5c11",
      "handle": "linen-shirt-white",
      "title": "Linen Shirt White",
      "description": "<p>Light linen shirt.</p>",
      "price_cents": 3950,
      "compare_price_cents": 4900,
      "cogs_cents": 1400,
      "images": [
        "https://cdn.example.com/p/linen-shirt-1.jpg"
      ],
      "stock": 42,
      "active": true,
      "product_type": "physical",
      "options": [
        {
          "name": "Size",
          "values": [
            "S",
            "M",
            "L"
          ]
        }
      ],
      "variants": [
        {
          "id": "v1",
          "title": "M",
          "sku": "LS-W-M",
          "stock": 18,
          "price_cents": 3950
        }
      ],
      "sku": "LS-W",
      "barcode": null,
      "category": "Tops",
      "vendor": "Example Label",
      "tags": [
        "summer"
      ],
      "archived_at": null,
      "created_at": "2026-06-02T11:20:00.000Z",
      "updated_at": "2026-08-27T10:02:00.000Z"
    }
  ],
  "next_cursor": null
}

Retrieve a product#

GET/api/public/v1/products/{id}products:read

Retrieve one product by UUID or handle. If :id is a UUID it is matched against id, otherwise against handle.

Path parameters

iduuid | stringrequired

Product UUID or handle.

Query parameters

shop_iduuid

Only for OAuth tokens that cover several shops: the shop to query. Must be one of the token's shops (else 403 forbidden). Required when the token covers more than one shop (else 400 shop_required). Optional for API keys (a key belongs to exactly one shop; any other value returns 403).

Response fields

data.iduuid

Product id.

data.handlestring

URL handle (also accepted as :id on the detail endpoint).

data.titlestring

Product title.

data.descriptionstring|null

Product description (HTML/text as stored).

data.price_centsinteger

Price in minor units of the shop currency.

data.compare_price_centsinteger|null

Compare-at (strike-through) price.

data.cogs_centsinteger|null

Cost of goods per unit as entered by the merchant.

data.imagesarray (raw JSON)

Product images as stored.

data.stockinteger|null

Stock level (product level).

data.activeboolean

Whether the product is active/visible.

data.product_typestring|null

Product type (e.g. physical/digital) as stored.

data.optionsarray (raw JSON)

Option definitions as stored.

data.variantsarray (raw JSON)

Variants as stored.

data.skustring|null

SKU.

data.barcodestring|null

Barcode (EAN/GTIN).

data.categorystring|null

Category.

data.vendorstring|null

Vendor/manufacturer.

data.tagsarray|null

Tags.

data.archived_attimestamp|null

Set when the product is archived.

data.created_attimestamp

Creation time; pagination key.

data.updated_attimestamp

Last update.

Errors

400bad_request

Detail endpoints and PATCH.

404not_found

Detail endpoints.

401unauthorized

Any endpoint. Response carries header WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource".

403forbidden

Scope check per endpoint (and per body field on PATCH /orders/:id).

403forbidden

shop_id query parameter names a shop outside the credential's reach.

400shop_required

Multi-shop OAuth token without shop_id.

404not_found

Any endpoint when the resolved shop has active=false.

429rate_limited

Any endpoint. Header Retry-After (seconds until the next minute bucket).

500server_error

Any endpoint.

Try itNot authorized
Request
curl "https://api.ecomone.shop/api/public/v1/products/thermo-socks" \
  -H "X-Api-Key: $ECOMONE_API_KEY" \
  -H "X-Api-Secret: $ECOMONE_API_SECRET"
200Response
{
  "data": {
    "id": "3b8b1f0a-1d2c-4f34-8a7c-6e2f9b4d5c11",
    "handle": "linen-shirt-white",
    "title": "Linen Shirt White",
    "description": "<p>Light linen shirt.</p>",
    "price_cents": 3950,
    "compare_price_cents": 4900,
    "cogs_cents": 1400,
    "images": [
      "https://cdn.example.com/p/linen-shirt-1.jpg"
    ],
    "stock": 42,
    "active": true,
    "product_type": "physical",
    "options": [
      {
        "name": "Size",
        "values": [
          "S",
          "M",
          "L"
        ]
      }
    ],
    "variants": [
      {
        "id": "v1",
        "title": "M",
        "sku": "LS-W-M",
        "stock": 18,
        "price_cents": 3950
      }
    ],
    "sku": "LS-W",
    "barcode": null,
    "category": "Tops",
    "vendor": "Example Label",
    "tags": [
      "summer"
    ],
    "archived_at": null,
    "created_at": "2026-06-02T11:20:00.000Z",
    "updated_at": "2026-08-27T10:02:00.000Z"
  }
}

Authorize requests

Requests go straight from your browser to https://api.ecomone.shop. Your credentials stay in this browser tab and are never sent to this documentation site.