Collections and Tags

Group products into ordered collections and label them with tags, from the Dashboard or the API, and filter storefront product lists by either.

Collections and tags help buyers find your products. Neither changes a product's price, billing or checkout: they only decide how products are grouped and filtered.

	Collection	Tag
What it is	A named, ordered group of products, such as "Massage" or "Gift ideas"	A short label on a product, such as `sports` or `60-min`
Order	You set the order of products in the collection	No order
Has its own page data	Yes: name, URL handle, description, image	No
A product can be in	Any number of collections	Up to 50 tags
Managed with	`/v2/product-collections`	The `tags` field on a product

In the Dashboard

Go to Products > Collections and click New collection.
Enter a name. RevKeen suggests a URL handle from it, which you can change. Add a description if you want one, and choose the products in the order buyers should see them.
Click Create collection. To change the products or their order later, edit the collection. To remove it, delete it: deleting a collection does not change or delete its products.

With the API

Collections use the products:read and products:write scopes. Every response wraps the collection in data.

The published TypeScript SDK does not yet include collection methods, so the examples use HTTP directly.

Create a collection

curl https://staging-api.revkeen.com/v2/product-collections \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Massage",
    "slug": "massage",
    "description": "Sports and deep tissue massage",
    "product_ids": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"
    ]
  }'

const response = await fetch("https://staging-api.revkeen.com/v2/product-collections", {
  method: "POST",
  headers: {
    "x-api-key": process.env.REVKEEN_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Massage",
    slug: "massage",
    product_ids: [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222",
    ],
  }),
});
const { data: collection } = await response.json();

slug is the URL handle: lower-case letters, numbers and single hyphens, up to 80 characters, unique in your account.
product_ids lists products in display order, up to 500. Every product must belong to your account.
position (optional) orders collections relative to each other.

Read, update and delete

Operation	Request
List collections	`GET /v2/product-collections`
Get one	`GET /v2/product-collections/{id}` (the ID or the URL handle)
Update	`PATCH /v2/product-collections/{id}`
Delete	`DELETE /v2/product-collections/{id}`

On update, product_ids replaces the whole membership in the order you send. To add one product, read the collection, add the ID to its product_ids, and send the full list back.

Each collection has a version that increases on every change. Send it back as expected_version so your update is refused if someone else changed the collection since you read it:

curl -X PATCH https://staging-api.revkeen.com/v2/product-collections/massage \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_ids": [
      "22222222-2222-2222-2222-222222222222",
      "11111111-1111-1111-1111-111111111111",
      "33333333-3333-3333-3333-333333333333"
    ],
    "expected_version": 4
  }'

Errors

Status	`code`	Cause
`404`	`PRODUCT_COLLECTION_NOT_FOUND`	No collection with that ID or handle in your account
`409`	`PRODUCT_COLLECTION_CONFLICT`	The URL handle is already used, or `expected_version` no longer matches
`422`	`PRODUCT_COLLECTION_INVALID_PRODUCTS`	One or more `product_ids` are not products in your account; they are listed in `product_ids`

On a 409 version conflict, read the collection again and reapply your change.

Filter storefront product lists

GET /v2/storefront/products lists your active, purchasable products with browser-safe display data. Filter it by collection or tag:

Query parameter	Effect
`collection`	Only products in this collection (ID or URL handle)
`tag`	Only products with this tag
`search`	Case-insensitive match on name or description
`sort`	`featured` (collection order when `collection` is set, otherwise newest), `newest`, `name`, `price_asc` or `price_desc`

curl "https://staging-api.revkeen.com/v2/storefront/products?collection=massage&sort=featured" \
  -H "x-api-key: rk_pk_sandbox_..."

This endpoint accepts a publishable key (rk_pk_*), so you can call it from a browser. A browser call must come from an origin you have registered in Dashboard > Commerce > Embed. See Embed.

Webhooks

There are no public webhook events for collections yet. If you mirror collections into another system, read them from the API.

Owner: david · Reviewed 30 Sep 2026 · Next review 30 Oct 2026

Collections and Tags

On this page