Products

Products are the core of your store. Each product has a title, a handle (used in URLs), one or more variants (sizes, colours), and a set of images. The API returns all of this in a flat shape so you can build product cards, detail pages, and search results with ease.

List products

Returns a page of active products with their variants and images. Use the query string to search by title or filter by collection. The default page size is 25 but you can go up to 100.

GET /v1/products

Auth: Publishable or secret key

Query parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`per_page`	integer	25	Items per page (max 100)
`q`	string	-	Search by product title
`collection`	string	-	Filter by collection handle

Response

{
  "data": [
    {
      "id": 42,
      "public_id": "01J5ABC...",
      "title": "Classic Tee",
      "subtitle": "Organic cotton, relaxed fit",
      "handle": "classic-tee",
      "description": "A comfortable everyday tee made from 100% organic cotton.",
      "vendor": "Basics Co",
      "product_type": "Apparel",
      "tags": ["cotton", "basics", "summer"],
      "fulfillment_type": "physical",
      "option_definitions": [
        { "name": "Size", "position": 1, "values": ["Small", "Medium", "Large"] },
        { "name": "Colour", "position": 2, "values": ["Black", "White"] }
      ],
      "seo_title": "Classic Tee | My Store",
      "seo_description": "A comfortable everyday tee made from organic cotton.",
      "length": 30,
      "width": 20,
      "height": 5,
      "dimension_unit": "cm",
      "isbn": null,
      "image_url": "https://cdn.quantm7.com/store/products/abc123.webp",
      "product_details": { "Material": "Organic Cotton", "Fit": "Relaxed" },
      "show_product_details": true,
      "instructions": "Machine wash cold. Tumble dry low.",
      "brand": "Basics Co",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-07-20T14:22:00.000Z",
      "variants": [
        {
          "id": 101,
          "sku": "CT-SM-BLK",
          "barcode": "5060000000001",
          "gtin": null,
          "title": "Small / Black",
          "price": 29.99,
          "compare_at_price": 39.99,
          "inventory_quantity": 24,
          "in_stock": true,
          "weight": 0.2,
          "weight_unit": "kg",
          "requires_shipping": true,
          "country_of_origin": "GB",
          "hs_code": "6109100010",
          "image_id": null,
          "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, front view",
          "width": 1200,
          "height": 1600,
          "position": 1
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 84
  }
}

Product fields

Field	Type	Description
`id`	integer	Product ID
`public_id`	string	Stable public UUID
`title`	string	Product name
`subtitle`	string or null	Short tagline
`handle`	string	URL-safe slug
`description`	string or null	Full product description (may contain HTML)
`vendor`	string or null	Product vendor or manufacturer
`product_type`	string or null	Product category type
`tags`	string array or null	Product tags
`fulfillment_type`	string	One of `physical`, `digital_download`, `service`, `digital_service`
`option_definitions`	array or null	Variant option config (see below)
`seo_title`	string or null	SEO page title
`seo_description`	string or null	SEO meta description
`length`	number or null	Package length
`width`	number or null	Package width
`height`	number or null	Package height
`dimension_unit`	string or null	Dimension unit (`cm`, `in`, `m`)
`isbn`	string or null	ISBN for books and media
`image_url`	string or null	Primary image URL
`product_details`	object or null	Key-value pairs (e.g. material, dimensions)
`show_product_details`	boolean or null	Whether to display product details
`instructions`	string or null	Care or usage instructions
`brand`	string or null	Brand name
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Option definitions

Use option_definitions to build variant selectors (size pickers, colour swatches). Each entry has a name, position, and values array.

[
  { "name": "Size", "position": 1, "values": ["Small", "Medium", "Large"] },
  { "name": "Colour", "position": 2, "values": ["Black", "White", "Navy"] }
]

Products with a single "Default" variant have option_definitions: null.

Variant fields

Field	Type	Description
`id`	integer	Variant ID
`sku`	string or null	Stock keeping unit
`barcode`	string or null	UPC, EAN, or other barcode
`gtin`	string or null	Global Trade Item Number
`title`	string	Variant name (e.g. "Small / Black")
`price`	number	Current price
`compare_at_price`	number or null	Original price (for showing discounts)
`inventory_quantity`	integer	Exact units in stock
`in_stock`	boolean	Whether the variant is available to purchase
`weight`	number or null	Variant weight
`weight_unit`	string or null	Weight unit (`g`, `kg`, `lb`, `oz`)
`requires_shipping`	boolean	Whether the variant needs physical shipping
`country_of_origin`	string or null	Two-letter ISO country code
`hs_code`	string or null	Harmonized System customs code
`image_id`	integer or null	ID of the variant-specific image
`position`	integer	Sort order
`options`	object	Option key-value pairs (e.g. `{ "Size": "Small" }`)

Image fields

Field	Type	Description
`id`	integer	Image ID
`src`	string	Full image URL
`alt_text`	string or null	Alt text for accessibility
`width`	integer or null	Image width in pixels
`height`	integer or null	Image height in pixels
`position`	integer	Sort order (1 = primary image)

Get a product

Returns a single product by its handle, including linked variants and product addons.

GET /v1/products/{handle}

Auth: Publishable or secret key

Path parameters

Parameter	Type	Description
`handle`	string	Product handle (URL slug)

Response

The response includes all the fields from the list endpoint, plus:

{
  "data": {
    "id": 42,
    "title": "Classic Tee",
    "handle": "classic-tee",
    "variants": [ "..." ],
    "images": [ "..." ],
    "linked_variants": [
      {
        "product_id": 43,
        "handle": "classic-tee-v-neck",
        "label": "V-Neck",
        "image_url": "https://cdn.quantm7.com/store/products/def456.webp",
        "is_current": false
      },
      {
        "product_id": 42,
        "handle": "classic-tee",
        "label": "Crew Neck",
        "image_url": "https://cdn.quantm7.com/store/products/abc123.webp",
        "is_current": true
      }
    ],
    "addons": {
      "pairs_with": [
        {
          "id": 50,
          "title": "Leather Belt",
          "handle": "leather-belt",
          "image_url": "https://cdn.quantm7.com/store/products/belt.webp",
          "price": 45.00,
          "compare_at_price": null,
          "in_stock": true
        }
      ]
    }
  }
}

Linked variant fields

Field	Type	Description
`product_id`	integer	ID of the linked product
`handle`	string	Handle of the linked product
`label`	string	Display label (e.g. "V-Neck", "14K Gold")
`image_url`	string or null	Image for the linked variant
`is_current`	boolean	Whether this entry is the current product

Linked variants let you tie related products into a group. For example, the same shirt in crew neck and v-neck can link to each other. The current product is always in the list with is_current: true so you can highlight it in your UI.

Product addons

The addons field is an object keyed by addon type. Each type contains an array of related products. Use these to show "You might also like" or "Don't forget" sections.

Addon type	Suggested label
`pairs_with`	"Pairs well with"
`dont_forget`	"Don't forget"
`youll_also_need`	"You'll also need"
`recommended_add_ons`	"Recommended add-ons"
`complete_the_set`	"Complete the set"
`compatible_with`	"Compatible with"

If a product has no addons, the field is an empty object {}.

Errors

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

Examples

Search for products:

curl "https://api.quantm7.com/v1/products?q=tee&per_page=10" \
  -H "Authorization: Bearer q7_pk_your_key"

Filter by collection:

curl "https://api.quantm7.com/v1/products?collection=summer-2026" \
  -H "Authorization: Bearer q7_pk_your_key"

Get a single product:

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

On this page