Skip to main content

Organize products into collections

Group products into collections so shoppers can browse them.

When to use this​

Building category pages, promotional groupings, or auto-categorizing products by tag.

Prerequisites​

  • A working public app with OAuth and token storage — follow Develop app first. Every request below carries an Access-Token: {token} header, using the token you saved for each shop.
  • The collection access scope granted during OAuth.

How it works​

A collection is the container that groups products for browsing; a collect is the membership record that links one product to one collection.

  • A manual collection (smart: false) holds only the products you explicitly add as collects — you pick them one by one (or in batch).
  • A smart collection (smart: true) auto-includes any product that matches its rules (tag, price, vendor, and so on) — you never add collects yourself. Smart collections are created asynchronously: the create call returns a task, and you poll it until the collection is ready.

Create a manual collection​

Set smart: false for a manual collection — you control exactly which products belong.

POST /openapi/2026-01/collections

Request body:

{
  "collection": {
    "title": "Summer picks",
    "smart": false // false = manual collection, you choose the products
  }
}

Response (excerpt, collection under data.data.collection):

{
  "code": "Success",
  "data": {
    "collection": {
      "id": "9574a4b4-1b85-42fc-9b8c-b47e26640cc0",
      "title": "Summer picks",
      "handle": "summer-picks",
      "sort_order": "manual",
      "created_at": "2026-07-02T02:58:32Z",
      "updated_at": "2026-07-02T02:58:32Z"
    }
  }
}
warning

Set smart: false explicitly for a manual collection. Omitting it can route the request through the smart-collection (asynchronous) path and fail. See Create collection.

Add a product to the collection​

A collect links one product to one collection.

POST /openapi/2026-01/collects

Request body:

{
  "collect": {
    "collection_id": "9574a4b4-1b85-42fc-9b8c-b47e26640cc0", // the collection's id
    "product_id": "4d3e7859-455c-4899-a296-7befe731c585"
  }
}

Response (excerpt, collect under data.data.collect):

{
  "code": "Success",
  "data": {
    "collect": {
      "id": "cc6ae5d9-fdc8-4c6a-a413-a9218ed9db0e",
      "collection_id": "9574a4b4-1b85-42fc-9b8c-b47e26640cc0",
      "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
      "position": 1,
      "created_at": "2026-07-02T02:58:34Z",
      "updated_at": "2026-07-02T02:58:34Z"
    }
  }
}

Full fields: see Create collect.

To add many products at once, use POST /collects/batch — see Batch create collect. To remove a product, delete its collect with DELETE /collects/{id} (Delete collect).

Create a smart collection​

A smart collection auto-includes products that match rules (tags, price, vendor, and so on). It is created asynchronously: create it, then poll the task.

POST /openapi/2026-01/collections/async

Request body:

{
  "collection": {
    "title": "New arrivals",
    "smart": true, // true = smart collection, products are matched automatically
    "match_rules": [
      { "column": "tag", "relation": "equals", "condition": "new" } // match rule: tag equals "new"
    ]
  }
}

Response: an async task with a task id — see Async create collection. Poll GET /collections/async-task/{id} until it completes — see Get collection async task — then refine rules with PATCH /collections/{id}/smart-rule. See Update smart collection rules. To update smart rules asynchronously, use Update smart collection rules (async).

Update or delete a collection​

Update or delete a collection by id.

PUT /openapi/2026-01/collections/{id}

Request body:

{
  "collection": {
    "title": "Summer picks (updated)" // any field you want to change
  }
}

Returns the updated collection — see Update collection.

DELETE /openapi/2026-01/collections/{id}

See Delete collection.

List collections and collects​

List collections with GET /collections, or fetch one with GET /collections/{id}. List the collects (memberships) with GET /collects. Each has a count endpoint too.

See List collections, Get collection, Count collections, and List collects.

Next steps​