# Organize products into collections

> Group Shoplazza products into manual and smart collections with the Open API, add products to them, and list collections and collects from your app.

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 a standalone app](/docs/app/getting-started/create-public-app/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:

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

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

```json
{
  "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](/api/collection-create).
:::

### Add a product to the collection

A collect links one product to one collection.

`POST /openapi/2026-01/collects`

Request body:

```json5
{
  "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`):

```json
{
  "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](/api/collect-create).

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

### 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:

```json5
{
  "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](/api/collection-async-create). Poll `GET /collections/async-task/{id}` until it completes — see [Get collection async task](/api/collection-async-task-detail) — then refine rules with `PATCH /collections/{id}/smart-rule`. See [Update smart collection rules](/api/smart-collection-rule-update). To update smart rules asynchronously, use [Update smart collection rules (async)](/api/smart-collection-rule-async-update).

### Update or delete a collection

Update or delete a collection by id.

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

Request body:

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

Returns the updated collection — see [Update collection](/api/collection-update).

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

See [Delete collection](/api/collection-delete).

## 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](/api/collections), [Get collection](/api/collection-detail), [Count collections](/api/collection-count), and [List collects](/api/collects).

## Next steps

- [Manage inventory](/docs/app/use-cases/product-merchandising/manage-inventory)
- [Create and update products](/docs/app/use-cases/product-merchandising/create-and-update-products)