Collections

Collections group your products into sets like "Summer 2026" or "Best Sellers". Use the list endpoint to show all groups on a shop page. Use the detail endpoint to show the products in a single group.

List collections

Returns all published collections for your store. Each collection includes its name, image, and SEO fields. Use this to build a "Shop by Category" page or a nav menu.

GET /v1/collections

Auth: Publishable or secret key

Response

{
  "data": [
    {
      "id": 5,
      "public_id": "01J5ABC...",
      "name": "Summer 2026",
      "handle": "summer-2026",
      "description": "Lightweight styles for warm weather.",
      "image_src": "https://cdn.quantm7.com/store/collections/summer.webp",
      "image_alt": "Summer collection hero image",
      "seo_title": "Summer 2026 Collection",
      "seo_description": "Shop lightweight summer styles.",
      "position": 1,
      "product_count": 12
    }
  ]
}

Collection fields

Field	Type	Description
`id`	integer	Collection ID
`public_id`	string	Public UUID (for external references)
`name`	string	Collection name
`handle`	string	URL-safe slug
`description`	string or null	Collection description
`image_src`	string or null	Hero image URL
`image_alt`	string or null	Image alt text
`seo_title`	string or null	SEO page title
`seo_description`	string or null	SEO meta description
`position`	integer	Sort order
`product_count`	integer	Number of products in this collection

Get a collection

Returns a single collection with its products, linked collections, and sub-collections.

GET /v1/collections/{handle}

Auth: Publishable or secret key

Path parameters

Parameter	Type	Description
`handle`	string	Collection handle

Query parameters

Parameter	Type	Default	Description
`page`	integer	1	Product page number
`per_page`	integer	25	Products per page (max 100)

Response

{
  "data": {
    "id": 5,
    "public_id": "01J5ABC...",
    "name": "Summer 2026",
    "handle": "summer-2026",
    "description": "Lightweight styles for warm weather.",
    "image_src": "https://cdn.quantm7.com/store/collections/summer.webp",
    "image_alt": "Summer collection hero image",
    "seo_title": "Summer 2026 Collection",
    "seo_description": "Shop lightweight summer styles.",
    "position": 1,
    "products": [
      {
        "id": 42,
        "title": "Classic Tee",
        "subtitle": "Organic cotton, relaxed fit",
        "handle": "classic-tee",
        "description": "A comfortable everyday tee.",
        "image_url": "https://cdn.quantm7.com/store/products/abc123.webp",
        "variants": [
          {
            "id": 101,
            "sku": "CT-SM-BLK",
            "title": "Small / Black",
            "price": 29.99,
            "compare_at_price": 39.99,
            "in_stock": true,
            "position": 1,
            "options": { "Size": "Small", "Colour": "Black" }
          }
        ],
        "images": [
          {
            "id": 201,
            "src": "https://cdn.quantm7.com/store/products/abc123.webp",
            "alt_text": "Classic Tee in black",
            "position": 1
          }
        ]
      }
    ],
    "products_meta": {
      "page": 1,
      "per_page": 25,
      "total": 12
    },
    "linked_collections": [
      {
        "id": 6,
        "name": "New Arrivals",
        "handle": "new-arrivals",
        "image_src": "https://cdn.quantm7.com/store/collections/new.webp",
        "image_alt": "New arrivals"
      }
    ],
    "sub_collections": [
      {
        "id": 10,
        "name": "Summer Dresses",
        "handle": "summer-dresses"
      }
    ]
  }
}

Linked collections

You can link one collection to another as an "Also see" hint. For example, "Summer Dresses" might link to "New Arrivals". Links work both ways. If you link A to B, then B also shows A in its response. Use these to help shoppers find related groups.

Child collections

Collections can sit inside other collections. A parent like "Clothing" can have children like "Tops" and "Dresses". When you fetch a parent, sub_collections lists its children. When you fetch a child, it lists its parent and its siblings so you can build breadcrumbs or a sidebar.

Errors

Status	Code	Description
404	`not_found`	No collection with this handle exists

Examples

List all collections:

curl https://api.quantm7.com/v1/collections \
  -H "Authorization: Bearer q7_pk_your_key"

Get a collection with products (page 2):

curl "https://api.quantm7.com/v1/collections/summer-2026?page=2&per_page=12" \
  -H "Authorization: Bearer q7_pk_your_key"

On this page