Collections API

Unlike products/orders/customers, collections have a real single-resource GET /:id route.

List collections

GET /platform/v1/collections — scope read_collections, cursor-paginated.

const { collections, nextCursor } = await client.listCollections(cursor, 50);

{
  "collections": [
    { "id": "...", "title": "Summer Sale", "type": "automated", "isActive": true, "productCount": 12, "productIds": ["..."] }
  ],
  "nextCursor": null
}

productIds are always live-resolved

For type: "automated" (rule-based) collections, productIds is computed fresh on every read from the collection's own rules — never a stale snapshot. A product edited after the collection was created still shows up correctly here and on the storefront. type: "manual" collections pass through unchanged (already live — hand-picked), at zero extra query cost.

Get one collection

GET /platform/v1/collections/:id — scope read_collections.

const { data } = await client.getCollection(collectionId);

Create a collection

POST /platform/v1/collections — scope write_collections, requires Idempotency-Key. Only title is required.

curl -X POST https://admin.prebit.in/api/platform/v1/collections \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "title": "Summer Sale", "type": "automated", "rules": [{"field":"tags","relation":"equals","value":"summer"}] }'

A newly-created automated collection's response already reflects any existing matching products — never a false "empty" result.

Editable fields

title (required on create), description, imageUrl, productIds (manual collections), isActive, slug, seoTitle, metaDescription, type ("manual" | "automated"), disjunctive, rules ({ field, relation, value }[]).

Update / delete

await client.updateCollection(collectionId, { isActive: false }, crypto.randomUUID());
await client.deleteCollection(collectionId, crypto.randomUUID());

Both scope write_collections, both require Idempotency-Key. Delete has no domain event (matches the Products API's own deferred .deleted event — see Products).

Domain events

Every collection write emits catalog.collection.updated.v1, with the same originInstallationId loop-prevention as products. See Webhooks.

Errors

Same shapes as Products: 400 invalid body/id, 404 store or collection not found, 409 idempotency key reused with a different body.