@mercurjs/docs 2.2.0-canary.40

package/content/references/api/store/product-attributes/list-product-attributes.mdx

@@ -0,0 +1,134 @@
+---
+title: "List Product Attributes"
+api: "GET /store/product-attributes"
+description: "Retrieve active global product attributes."
+---
+
+Returns a paginated list of active, global product attributes (attributes scoped to a single product are excluded).
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  Maximum number of attributes to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  Number of attributes to skip before collecting results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  Field to sort by, prefixed with `-` for descending order.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Free-text search term applied to attribute fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by one or more attribute IDs.
+</ParamField>
+
+<ParamField query="handle" type="string | string[]">
+  Filter by one or more attribute handles.
+</ParamField>
+
+<ParamField query="type" type="string | string[]">
+  Filter by attribute type. Values: `single_select`, `multi_select`, `unit`, `toggle`, `text`.
+</ParamField>
+
+<ParamField query="is_variant_axis" type="boolean">
+  Filter attributes that define variant axes.
+</ParamField>
+
+<ParamField query="is_filterable" type="boolean">
+  Filter attributes usable as storefront filters.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="$and" type="object[]">
+  Join multiple filter objects with a logical AND.
+</ParamField>
+
+<ParamField query="$or" type="object[]">
+  Join multiple filter objects with a logical OR.
+</ParamField>
+
+## Response
+
+<ResponseField name="product_attributes" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The attribute's ID.</ResponseField>
+    <ResponseField name="name" type="string">The attribute's display name.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="description" type="string | null">The attribute's description.</ResponseField>
+    <ResponseField name="type" type="string">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ResponseField>
+    <ResponseField name="is_required" type="boolean">Whether sellers must set a value.</ResponseField>
+    <ResponseField name="is_filterable" type="boolean">Whether the attribute can drive storefront filters.</ResponseField>
+    <ResponseField name="is_variant_axis" type="boolean">Whether the attribute defines a variant axis.</ResponseField>
+    <ResponseField name="product_id" type="null">Always `null` on the store API (global attributes only).</ResponseField>
+    <ResponseField name="rank" type="number">Sort rank.</ResponseField>
+    <ResponseField name="values" type="object[]">The attribute's predefined values.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching attributes.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped attributes.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned attributes.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/product-attributes?is_filterable=true' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { product_attributes, count } = await client.store.productAttributes.query({
+  is_filterable: true,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_attributes": [
+    {
+      "id": "attr_01JB2K7A1B",
+      "name": "Material",
+      "handle": "material",
+      "description": null,
+      "type": "single_select",
+      "is_required": false,
+      "is_filterable": true,
+      "is_variant_axis": false,
+      "product_id": null,
+      "rank": 0,
+      "values": [
+        { "id": "attrval_01JB2K7C2D", "name": "Linen", "rank": 0 },
+        { "id": "attrval_01JB2K7E3F", "name": "Cotton", "rank": 1 }
+      ],
+      "metadata": null,
+      "created_at": "2026-05-01T10:00:00.000Z",
+      "updated_at": "2026-05-01T10:00:00.000Z"
+    }
+  ],
+  "count": 5,
+  "offset": 0,
+  "limit": 50
+}
+```
+</ResponseExample>

package/content/references/api/store/product-attributes/retrieve-product-attribute.mdx

@@ -0,0 +1,78 @@
+---
+title: "Retrieve Product Attribute"
+api: "GET /store/product-attributes/{id}"
+description: "Retrieve an active global product attribute by ID."
+---
+
+Returns a single active, global product attribute; inactive or product-scoped attributes return a `404`.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The attribute's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Response
+
+<ResponseField name="product_attribute" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The attribute's ID.</ResponseField>
+    <ResponseField name="name" type="string">The attribute's display name.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="description" type="string | null">The attribute's description.</ResponseField>
+    <ResponseField name="type" type="string">One of `single_select`, `multi_select`, `unit`, `toggle`, `text`.</ResponseField>
+    <ResponseField name="is_required" type="boolean">Whether sellers must set a value.</ResponseField>
+    <ResponseField name="is_filterable" type="boolean">Whether the attribute can drive storefront filters.</ResponseField>
+    <ResponseField name="is_variant_axis" type="boolean">Whether the attribute defines a variant axis.</ResponseField>
+    <ResponseField name="product_id" type="null">Always `null` on the store API (global attributes only).</ResponseField>
+    <ResponseField name="rank" type="number">Sort rank.</ResponseField>
+    <ResponseField name="values" type="object[]">The attribute's predefined values.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/product-attributes/attr_01JB2K7A1B' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { product_attribute } = await client.store.productAttributes.$id.query({
+  $id: "attr_01JB2K7A1B",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_attribute": {
+    "id": "attr_01JB2K7A1B",
+    "name": "Material",
+    "handle": "material",
+    "description": null,
+    "type": "single_select",
+    "is_required": false,
+    "is_filterable": true,
+    "is_variant_axis": false,
+    "product_id": null,
+    "rank": 0,
+    "values": [
+      { "id": "attrval_01JB2K7C2D", "name": "Linen", "rank": 0 }
+    ],
+    "metadata": null,
+    "created_at": "2026-05-01T10:00:00.000Z",
+    "updated_at": "2026-05-01T10:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/store/product-categories/list-product-categories.mdx

@@ -0,0 +1,126 @@
+---
+title: "List Product Categories"
+api: "GET /store/product-categories"
+description: "Retrieve active, public product categories."
+---
+
+Returns a paginated list of product categories; inactive and internal categories are always excluded.
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  Maximum number of categories to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  Number of categories to skip before collecting results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  Field to sort by, prefixed with `-` for descending order.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Free-text search term applied to category fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by one or more category IDs.
+</ParamField>
+
+<ParamField query="handle" type="string | string[]">
+  Filter by one or more category handles.
+</ParamField>
+
+<ParamField query="parent_category_id" type="string | string[]">
+  Filter by parent category ID; pass `null` to fetch top-level categories.
+</ParamField>
+
+<ParamField query="include_ancestors_tree" type="boolean">
+  Include each category's ancestors in `parent_category`.
+</ParamField>
+
+<ParamField query="include_descendants_tree" type="boolean">
+  Include each category's descendants in `category_children`.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="$and" type="object[]">
+  Join multiple filter objects with a logical AND.
+</ParamField>
+
+<ParamField query="$or" type="object[]">
+  Join multiple filter objects with a logical OR.
+</ParamField>
+
+## Response
+
+<ResponseField name="product_categories" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The category's ID.</ResponseField>
+    <ResponseField name="name" type="string">The category's name.</ResponseField>
+    <ResponseField name="description" type="string">The category's description.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="rank" type="number">Sort rank among siblings.</ResponseField>
+    <ResponseField name="parent_category_id" type="string | null">ID of the parent category.</ResponseField>
+    <ResponseField name="parent_category" type="object | null">The parent category.</ResponseField>
+    <ResponseField name="category_children" type="object[]">Direct child categories.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching categories.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped categories.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned categories.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/product-categories?parent_category_id=null&limit=50' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { product_categories, count } = await client.store.productCategories.query({
+  parent_category_id: "null",
+  limit: 50,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_categories": [
+    {
+      "id": "pcat_01JB2K6A2B",
+      "name": "Shirts",
+      "description": "",
+      "handle": "shirts",
+      "rank": 0,
+      "parent_category_id": null,
+      "parent_category": null,
+      "category_children": [{ "id": "pcat_01JB2K6H7J", "name": "Linen Shirts" }],
+      "metadata": null,
+      "created_at": "2026-05-01T10:00:00.000Z",
+      "updated_at": "2026-05-01T10:00:00.000Z"
+    }
+  ],
+  "count": 8,
+  "offset": 0,
+  "limit": 50
+}
+```
+</ResponseExample>

package/content/references/api/store/product-categories/retrieve-product-category.mdx

@@ -0,0 +1,79 @@
+---
+title: "Retrieve Product Category"
+api: "GET /store/product-categories/{id}"
+description: "Retrieve an active, public product category by ID."
+---
+
+Returns a single category; inactive or internal categories return a `404`.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The category's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="include_ancestors_tree" type="boolean">
+  Include the category's ancestors in `parent_category`.
+</ParamField>
+
+<ParamField query="include_descendants_tree" type="boolean">
+  Include the category's descendants in `category_children`.
+</ParamField>
+
+## Response
+
+<ResponseField name="product_category" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The category's ID.</ResponseField>
+    <ResponseField name="name" type="string">The category's name.</ResponseField>
+    <ResponseField name="description" type="string">The category's description.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="rank" type="number">Sort rank among siblings.</ResponseField>
+    <ResponseField name="parent_category_id" type="string | null">ID of the parent category.</ResponseField>
+    <ResponseField name="parent_category" type="object | null">The parent category.</ResponseField>
+    <ResponseField name="category_children" type="object[]">Direct child categories.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/product-categories/pcat_01JB2K6A2B?include_descendants_tree=true' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { product_category } = await client.store.productCategories.$id.query({
+  $id: "pcat_01JB2K6A2B",
+  include_descendants_tree: true,
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "product_category": {
+    "id": "pcat_01JB2K6A2B",
+    "name": "Shirts",
+    "description": "",
+    "handle": "shirts",
+    "rank": 0,
+    "parent_category_id": null,
+    "parent_category": null,
+    "category_children": [{ "id": "pcat_01JB2K6H7J", "name": "Linen Shirts" }],
+    "metadata": null,
+    "created_at": "2026-05-01T10:00:00.000Z",
+    "updated_at": "2026-05-01T10:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/store/products/list-products.mdx

@@ -0,0 +1,184 @@
+---
+title: "List Products"
+api: "GET /store/products"
+description: "Retrieve published products from visible sellers."
+---
+
+Returns a paginated list of published products belonging to open, visible sellers.
+
+<Note>
+  Customer authentication is optional. When a customer token is provided, the customer's group memberships are included in the pricing context, which can change `variants.calculated_price` results. Variant prices are only computed when you request `variants.calculated_price` in `fields` (or pass `region_id`); the calculated price reflects the cheapest offer for each variant.
+</Note>
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  Maximum number of products to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  Number of products to skip before collecting results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  Field to sort by, prefixed with `-` for descending order (for example `-created_at`).
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Free-text search term applied to product fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by one or more product IDs.
+</ParamField>
+
+<ParamField query="title" type="string">
+  Filter by exact product title.
+</ParamField>
+
+<ParamField query="handle" type="string">
+  Filter by product handle.
+</ParamField>
+
+<ParamField query="collection_id" type="string | string[]">
+  Filter by one or more collection IDs.
+</ParamField>
+
+<ParamField query="type_id" type="string | string[]">
+  Filter by one or more product type IDs.
+</ParamField>
+
+<ParamField query="category_id" type="string | string[]">
+  Filter by one or more category IDs; only active, non-internal categories match.
+</ParamField>
+
+<ParamField query="tag_id" type="string | string[]">
+  Filter by one or more tag IDs.
+</ParamField>
+
+<ParamField query="is_giftcard" type="boolean">
+  Filter by gift-card products.
+</ParamField>
+
+<ParamField query="region_id" type="string">
+  Region used to build the pricing context for `variants.calculated_price`.
+</ParamField>
+
+<ParamField query="currency_code" type="string">
+  Currency used in the pricing context.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="$and" type="object[]">
+  Join multiple filter objects with a logical AND.
+</ParamField>
+
+<ParamField query="$or" type="object[]">
+  Join multiple filter objects with a logical OR.
+</ParamField>
+
+## Response
+
+<ResponseField name="products" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The product's ID.</ResponseField>
+    <ResponseField name="title" type="string">The product's title.</ResponseField>
+    <ResponseField name="subtitle" type="string | null">The product's subtitle.</ResponseField>
+    <ResponseField name="status" type="string">Always `published` on the store API.</ResponseField>
+    <ResponseField name="description" type="string | null">The product's description.</ResponseField>
+    <ResponseField name="handle" type="string">URL-safe handle.</ResponseField>
+    <ResponseField name="is_giftcard" type="boolean">Whether the product is a gift card.</ResponseField>
+    <ResponseField name="discountable" type="boolean">Whether promotions can apply to the product.</ResponseField>
+    <ResponseField name="thumbnail" type="string | null">Thumbnail URL.</ResponseField>
+    <ResponseField name="collection" type="object | null">The product's collection.</ResponseField>
+    <ResponseField name="type" type="object | null">The product's type.</ResponseField>
+    <ResponseField name="tags" type="object[]">The product's tags.</ResponseField>
+    <ResponseField name="images" type="object[]">The product's images.</ResponseField>
+    <ResponseField name="categories" type="object[]">The product's categories.</ResponseField>
+    <ResponseField name="options" type="object[]">Product options with their values.</ResponseField>
+    <ResponseField name="variants" type="object[]">
+      Product variants with their options; `calculated_price` and `offer_id` are added when requested and reflect the cheapest offer.
+    </ResponseField>
+    <ResponseField name="product_attribute_values" type="object[]">Attribute values assigned to the product, each with its parent attribute.</ResponseField>
+    <ResponseField name="scoped_attributes" type="object[]">Attributes scoped to this product, with their values.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching products.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped products.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned products.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/products?limit=20&region_id=reg_01JB2K4S1T&fields=*variants.calculated_price' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { products, count } = await client.store.products.query({
+  limit: 20,
+  region_id: "reg_01JB2K4S1T",
+  fields: "*variants.calculated_price",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "products": [
+    {
+      "id": "prod_01JB2K5M8N",
+      "title": "Linen Shirt",
+      "subtitle": null,
+      "status": "published",
+      "description": "A breathable linen shirt.",
+      "handle": "linen-shirt",
+      "is_giftcard": false,
+      "discountable": true,
+      "thumbnail": "https://cdn.example.com/linen-shirt.png",
+      "collection": null,
+      "type": null,
+      "tags": [],
+      "images": [],
+      "categories": [{ "id": "pcat_01JB2K6A2B", "name": "Shirts" }],
+      "options": [{ "id": "opt_01JB2K6C3D", "title": "Size", "values": [{ "value": "M" }] }],
+      "variants": [
+        {
+          "id": "variant_01JB2K6E4F",
+          "title": "M",
+          "offer_id": "offer_01JB2K6G5H",
+          "calculated_price": {
+            "calculated_amount": 4500,
+            "original_amount": 5000,
+            "currency_code": "eur"
+          }
+        }
+      ],
+      "product_attribute_values": [],
+      "scoped_attributes": [],
+      "metadata": null,
+      "created_at": "2026-05-01T10:00:00.000Z",
+      "updated_at": "2026-05-01T10:00:00.000Z"
+    }
+  ],
+  "count": 42,
+  "offset": 0,
+  "limit": 20
+}
+```
+</ResponseExample>