Docs / API reference / Collections

Collections

Product collections.

List collections#

GET/api/public/v1/collectionscollections:read

List collections, newest first. Lists collections of the shop.

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.

handlestring

Exact handle.

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

Collection id.

data[].titlestring

Title.

data[].handlestring

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

data[].descriptionstring|null

Description.

data[].image_urlstring|null

Image URL.

data[].sort_orderinteger|null

Sort order.

data[].activeboolean

Active flag.

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/collections?limit=10" \
  -H "X-Api-Key: $ECOMONE_API_KEY" \
  -H "X-Api-Secret: $ECOMONE_API_SECRET"

const res = await fetch("https://api.ecomone.shop/api/public/v1/collections?limit=10", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ECOMONE_API_KEY,
    "X-Api-Secret": process.env.ECOMONE_API_SECRET,
  },
});
if (!res.ok) throw new Error((await res.json()).message);
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.ecomone.shop/api/public/v1/collections?limit=10",
    headers={
        "X-Api-Key": os.environ["ECOMONE_API_KEY"],
        "X-Api-Secret": os.environ["ECOMONE_API_SECRET"],
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()["data"]

200Response

{
  "data": [
    {
      "id": "5c9a7d20-77f1-4a1e-9e0c-2b7c9f1a4e33",
      "title": "Summer Essentials",
      "handle": "summer-essentials",
      "description": "Light basics for warm days.",
      "image_url": "https://cdn.example.com/c/summer.jpg",
      "sort_order": 1,
      "active": true,
      "created_at": "2026-05-14T07:00:00.000Z",
      "updated_at": "2026-05-20T07:00:00.000Z"
    }
  ],
  "next_cursor": null
}

Retrieve a collection#

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

Retrieve one collection (by UUID or handle) with its product ids. Includes product_ids ordered by their position in the collection.

Path parameters

iduuid | stringrequired

Collection UUID or handle.

Query parameters

shop_iduuid

Response fields

data.iduuid

Collection id.

data.titlestring

Title.

data.handlestring

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

data.descriptionstring|null

Description.

data.image_urlstring|null

Image URL.

data.sort_orderinteger|null

Sort order.

data.activeboolean

Active flag.

data.created_attimestamp

Creation time; pagination key.

data.updated_attimestamp

Last update.

data.product_idsuuid[]

Products in the collection, ordered by position.

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/collections/winter" \
  -H "X-Api-Key: $ECOMONE_API_KEY" \
  -H "X-Api-Secret: $ECOMONE_API_SECRET"

const res = await fetch("https://api.ecomone.shop/api/public/v1/collections/winter", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ECOMONE_API_KEY,
    "X-Api-Secret": process.env.ECOMONE_API_SECRET,
  },
});
if (!res.ok) throw new Error((await res.json()).message);
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.ecomone.shop/api/public/v1/collections/winter",
    headers={
        "X-Api-Key": os.environ["ECOMONE_API_KEY"],
        "X-Api-Secret": os.environ["ECOMONE_API_SECRET"],
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()["data"]

200Response

{
  "data": {
    "id": "5c9a7d20-77f1-4a1e-9e0c-2b7c9f1a4e33",
    "title": "Summer Essentials",
    "handle": "summer-essentials",
    "description": "Light basics for warm days.",
    "image_url": "https://cdn.example.com/c/summer.jpg",
    "sort_order": 1,
    "active": true,
    "created_at": "2026-05-14T07:00:00.000Z",
    "updated_at": "2026-05-20T07:00:00.000Z",
    "product_ids": [
      "3b8b1f0a-1d2c-4f34-8a7c-6e2f9b4d5c11"
    ]
  }
}