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. A collection decides what is offered — on the Storefront, on checkout links and the embedded cart, and to discounts. It never decides what is in a customer's cart: prices, billing and checkout behaviour still come from the products themselves.
Collections vs Catalogue
The Catalogue holds everything you sell. A collection is a named selection of Catalogue products. A product can sit in several collections, or none.
Where a collection is used
Each collection has its own switch for the Storefront and for checkout links (which also covers the embedded cart), so a collection hidden from the Storefront can still feed a checkout link. Turning checkout links off makes every link offering that collection show an unavailable state until it is turned back on.
- Storefront: display and ordering, as before.
- Checkout links and embedded cart: a link can offer a whole collection, which stays in sync — new products appear on the link automatically — or specific hand-picked products.
- Discounts: a discount can apply to all products, specific products, or a collection. Products added to the collection later are discounted too.
Manual and automated collections
Manual collections are hand-picked. Automated collections follow a rule — currently, products carrying a given tag — and their membership cannot be edited by hand.
Mapping without opening the drawer
The ⋯ menu on a product, collection, checkout link or discount row maps things in two clicks: add a product to a collection, point a link at a collection, retarget a discount, and create a link or a 10% discount from whatever the row is showing.
| 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();slugis the URL handle: lower-case letters, numbers and single hyphens, up to 80 characters, unique in your account.product_idslists 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.
Tags
Tags live on the product. Set them with the tags field when you create or update a product. The list you send replaces the product's tags: up to 50 tags, each up to 50 characters.
curl -X PATCH https://staging-api.revkeen.com/v2/products/11111111-1111-1111-1111-111111111111 \
-H "x-api-key: $REVKEEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "tags": ["sports", "60-min"] }'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, price_desc or best_selling (units sold on paid orders in the last 90 days) |
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 > Sell on website. See Embed.
Webhooks
There are no public webhook events for collections yet. If you mirror collections into another system, read them from the API.
Related
Owner: david · Reviewed 30 Sep 2026 · Next review 30 Oct 2026