Collections API

REST API endpoints for managing product collections.

Collections group products together for display on your storefront (e.g. "Featured", "New Arrivals", "Sale Items"). YNS supports manual collections (products added individually) and several smart collection types that auto-include products based on price range, variant attributes, or recency.

List Collections

GET /api/v1/collections

Query Parameters

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "name": "Featured Products",
      "slug": "featured-products",
      "image": "https://cdn.example.com/featured.jpg",
      "filter": { "type": "manual" },
      "active": true,
      "productCollections": [
        { "productId": "0191abc0-0000-7000-8000-000000000100" }
      ],
      "translations": []
    }
  ],
  "meta": {
    "count": 1
  }
}

Get Collection

GET /api/v1/collections/:idOrSlug

Returns a single collection by UUID or slug, with associated products and translations. Supports ?lang= for translated content.

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Featured Products",
  "slug": "featured-products",
  "filter": { "type": "manual" },
  "active": true,
  "productCollections": [
    {
      "productId": "0191abc0-0000-7000-8000-000000000100",
      "product": {
        "id": "0191abc0-0000-7000-8000-000000000100",
        "name": "Classic Tee",
        "slug": "classic-tee"
      }
    }
  ]
}

Create Collection

POST /api/v1/collections

Creates a product collection. Slug is auto-generated from the name if not provided. Image URLs are downloaded and re-uploaded to the store's CDN.

Request Body

Filter Types

# Manual collection
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Featured", "filter": {"type": "manual"}}' \
  https://your-store.yns.store/api/v1/collections

# Dynamic price collection
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Budget Friendly", "filter": {"type": "dynamicPrice", "max": 50}}' \
  https://your-store.yns.store/api/v1/collections

# Variant attribute collection
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Red Products", "filter": {"type": "variantValues", "values": {"Color": ["Red"]}}}' \
  https://your-store.yns.store/api/v1/collections

# New arrivals (last 30 days)
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Arrivals", "filter": {"type": "newest", "days": 30}}' \
  https://your-store.yns.store/api/v1/collections

Response (201)

Returns the created collection with full data.

Update Collection

PATCH /api/v1/collections/:idOrSlug

Partially updates a collection by UUID or slug. Only provided fields change. Pass null to clear optional fields like description, image, or group.

Request Body

All fields from Create Collection are accepted and optional.

A collection that the store's Stock-based Pricing rule targets has to stay manual: that rule follows collection membership rows, which only a manual collection has. Changing its filter to a smart type is rejected with a 409 until the collection is removed from the rule in the dashboard.

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"type": "newest", "days": 14}, "group": "seasonal"}' \
  https://your-store.yns.store/api/v1/collections/new-arrivals

Response (200)

Returns the updated collection.

Errors

List a Collection's Products

GET /api/v1/collections/:idOrSlug/products

Returns the products a collection resolves to, with its own filter applied, in the collection's sortOrder. Unlike GET /api/v1/products?collection=..., it also covers smart collections.

Query Parameters

curl "https://your-store.yns.store/api/v1/collections/new-arrivals/products?sortOrder=price-ascending&limit=20"

The response is { "data": [...], "meta": { ... } }, where meta includes count, limit, offset and expandVariants.

Delete Collection

DELETE /api/v1/collections/:idOrSlug

Permanently deletes a collection by UUID or slug.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/collections/old-sale

Response (200)

{
  "ok": true,
  "deleted": 1
}

Translations

PUT /api/v1/collections/:idOrSlug/translations/:locale

Upsert or delete a single locale's translated fields for a collection. See the Localization page for the full field reference, behaviour, and examples.

Import Memberships (CSV)

POST /api/v1/collections/import-memberships
Content-Type: multipart/form-data

Bulk-import (collection_slug, product_slug) pairs into manual collections. Idempotent – existing memberships are skipped on re-runs. Rows targeting dynamic-filter collections are rejected per-row.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -F "file=@memberships.csv" \
  https://your-store.yns.store/api/v1/collections/import-memberships

Response

{
  "ok": true,
  "processed": 1000,
  "inserted": 950,
  "skipped_existing": 40,
  "errors": []
}