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 both manual collections (products added individually) and dynamic collections (products auto-included based on price range).

List Collections

GET /api/v1/collections

Query Parameters

Parameter	Type	Default	Description
`limit`	`number`	10	Collections per page (1-100)
`offset`	`number`	0	Collections to skip
`query`	`string`	—	Search by collection name
`active`	`boolean`	—	Filter by active status
`lang`	`string`	—	Locale code for translations (e.g. `pl-PL`)

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

Field	Type	Required	Description
`name`	`string`	Yes	Collection name
`slug`	`string`	No	URL slug (auto-generated from name)
`description`	`string`	No	Plain text description
`image`	`string`	No	Image URL
`filter`	`object`	No	Filter type (default: `{ type: "manual" }`)
`active`	`boolean`	No	Visible on storefront (default: `true`)

Filter Types

Type	Description
`{ type: "manual" }`	Products are manually added
`{ type: "dynamicPrice", min?: number, max?: number }`	Products auto-included by price range

# 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

Response (201)

Returns the created collection with full data.

PreviousCartsAPI Reference NextCategoriesAPI Reference