@mercurjs/docs 2.3.8-canary.3 → 2.3.9-canary.1

package/content/platform/attribute/guides/create-a-variant-axis.mdx

@@ -1,83 +1,132 @@
 ---
-title: "Create a variant axis"
+title: "Create a variant axis and build variants on it"
 sidebarTitle: "Create a variant axis"
-description: "Generate product variants from a multi_select axis attribute."
+description: "Create a multi_select axis attribute, then create a product whose variants bind to it."
 ---
 
-In this guide, you'll learn how to create a variant-axis attribute and use it to
-generate a product's variants from server code.
-
-A variant axis is a `multi_select` attribute with `is_variant_axis` set. Creating
-one mirrors a native Medusa `ProductOption`, so the values a product selects along
-the axis become the dimensions Medusa uses to generate variants.
-
-## Create the axis attribute
-
-```ts title="src/api/custom/attributes/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await createProductAttributesWorkflow(req.scope).run({
-    input: {
-      attributes: [
-        {
-          name: "Size",
-          type: "multi_select",
-          is_variant_axis: true,
-          is_filterable: true,
-          values: [{ name: "S" }, { name: "M" }, { name: "L" }],
-        },
-      ],
-    },
-  })
+Create a variant axis such as Size, then create a product that uses part of it and has one variant per selected value. You need this whenever products in your catalog come in sizes, colors, or any other dimension shoppers pick between.
 
-  res.status(201).json({ attribute: result[0] })
-}
-```
+## Before you begin
 
-The workflow creates the `ProductAttribute`, a mirror `ProductOption`, and a
-`ProductAttributeValue` for each option value. It wires `product_option_id` and
-`product_option_value_id` behind the scenes.
+You need the following:
 
-## Attach it to a product
+- **A Mercur server**: an API app with `@mercurjs/core` registered through `withMercur()`
+- **The concept**: read [Variant axes and product options](/platform/attribute/concepts/variant-axes) to see how an axis maps to a Medusa `ProductOption`
 
-Attach the axis to a product and pass the subset of values that product offers.
-Medusa generates a variant for each selected value.
+## Build the axis and the product
 
-```ts
-import { createAndLinkProductAttributesToProductWorkflow } from "@mercurjs/core/workflows"
+<Steps>
+  <Step title="Create the axis attribute">
+    An axis is a `multi_select` attribute with `is_variant_axis: true`. The workflow creates a global `ProductOption` titled `Size` with the same three values.
+
+    ```ts title="src/scripts/seed-size-axis.ts"
+    import type { ExecArgs } from "@medusajs/framework/types"
+    import { AttributeType } from "@mercurjs/types"
+    import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
 
+    export default async function seedSizeAxis({ container }: ExecArgs) {
+      const { result } = await createProductAttributesWorkflow(container).run({
+        input: {
+          attributes: [
+            {
+              name: "Size",
+              type: AttributeType.MULTI_SELECT,
+              is_variant_axis: true,
+              is_filterable: true,
+              values: [{ name: "S" }, { name: "M" }, { name: "L" }],
+            },
+          ],
+        },
+      })
+
+      container.resolve("logger").info(`Created axis ${result[0].id}`)
+    }
+    ```
+
+    Run it with `npx medusa exec ./src/scripts/seed-size-axis.ts`. Medusa keeps global option titles unique, so a second global axis named `Size` fails.
+  </Step>
+  <Step title="Create a product on the axis">
+    Mercur’s `createProductsWorkflow` takes `attributes` and `variants` together. It attaches the axis with the values you pick, then creates the variants against it.
+
+    ```ts
+    import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+    const { result } = await createProductsWorkflow(req.scope).run({
+      input: {
+        created_by: req.auth_context.actor_id,
+        products: [
+          {
+            title: "Linen shirt",
+            attributes: [
+              {
+                id: "pattr_01JD8Q1234567",
+                value_ids: ["pattrval_01JD8Q1", "pattrval_01JD8Q2"],
+              },
+            ],
+            variants: [
+              { title: "Linen shirt / S", options: { Size: "S" } },
+              { title: "Linen shirt / M", options: { Size: "M" } },
+            ],
+          },
+        ],
+      },
+    })
+    ```
+
+    Run this inside an authenticated route handler, so `req.auth_context.actor_id` records who created the product. Each variant names its option value by the option title, which is the attribute name. The product only holds `S` and `M`, so those are the variants it can have.
+  </Step>
+</Steps>
+
+## Change the values a product uses
+
+Run `createAndLinkProductAttributesToProductWorkflow` with an `update` entry to grow or shrink the subset. The workflow moves the option values on the product and the pivot links together.
+
+```ts
 await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
   input: {
-    product_id: "prod_shirt",
-    add: [{ id: "pattr_size", value_ids: ["pattrval_s", "pattrval_m"] }],
+    product_id: "prod_01JD8Q1234567",
+    update: [
+      {
+        id: "pattr_01JD8Q1234567",
+        add: ["pattrval_01JD8Q3"],
+        remove: ["pattrval_01JD8Q1"],
+      },
+    ],
   },
 })
 ```
 
-<Note>
-  Only `multi_select` attributes can be variant axes. The `value_ids` you pass
-  are the per-product subset of the axis's values. Only those become variants.
-</Note>
+After the run, the product offers `M` and `L`. Create the `L` variant with Medusa’s `createProductVariantsWorkflow` and `options: { Size: "L" }`.
 
-## Inline axes
+## Create an axis for one product
 
-To create a product-scoped axis in the same step it's attached, pass the inline
-form instead of an existing id. This creates an exclusive `ProductOption`, a
-scoped attribute (`product_id` set), and the value mirror in one call:
+When only one product needs a dimension, add an inline axis instead of a global one. It creates an exclusive option (`is_exclusive: true`), a product-scoped `multi_select` attribute, and its values, and attaches them to the product.
 
 ```ts
 await createAndLinkProductAttributesToProductWorkflow(req.scope).run({
   input: {
-    product_id: "prod_shirt",
-    add: [{ title: "Cut", is_variant_axis: true, values: ["Slim", "Regular"] }],
+    product_id: "prod_01JD8Q1234567",
+    add: [
+      { title: "Cut", is_variant_axis: true, values: ["Slim", "Regular"] },
+    ],
   },
 })
 ```
 
-<Tip>
-  Inline axes are ideal for a one-off dimension a single product needs. Reach for
-  a global axis attribute when the same dimension, such as Size or Color, recurs
-  across the catalog. See [Global vs inline](/platform/attribute/concepts/global-vs-inline).
-</Tip>
+An inline axis holds all of its values, so there’s no subset to pick. You add values to it later with `update` and `add: [{ value: "Relaxed" }]`.
+
+## Add values to a global axis
+
+`createProductAttributeValuesWorkflow` adds values to the attribute and to its global option in one run. Products don’t gain the new value until you add it to their subset.
+
+```ts
+await createProductAttributeValuesWorkflow(req.scope).run({
+  input: { attribute_id: "pattr_01JD8Q1234567", values: [{ name: "XL" }] },
+})
+```
+
+## Next steps
+
+- [Every add and update form for the batch workflow](/platform/attribute/guides/attach-attributes-to-a-product)
+- [Global and inline attributes](/platform/attribute/concepts/global-vs-inline)
+- [The workflows that keep the option in sync](/platform/attribute/reference/workflows)

package/content/platform/attribute/guides/create-an-attribute.mdx

@@ -1,81 +1,130 @@
 ---
-title: "Create an attribute"
+title: "Create a catalog attribute"
 sidebarTitle: "Create an attribute"
-description: "Create a typed catalog attribute with createProductAttributesWorkflow."
+description: "Create a global attribute with its values from a route, a seed script, or a catalog import."
 ---
 
-In this guide, you'll learn how to create a global catalog attribute from your
-own server code, for example in a seed script, a custom API route, or a catalog
-import.
+Create global catalog attributes from your own server code, for example when you seed a marketplace or import a taxonomy from a product information system.
 
-Mercur exposes a `createProductAttributesWorkflow` that creates one or more
-`ProductAttribute` records along with their values. Run it from any place that
-has access to the Medusa container.
+## Before you begin
 
-## Run the workflow
+You need the following:
 
-```ts title="src/api/custom/attributes/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+- **A Mercur server**: an API app with `@mercurjs/core` registered through `withMercur()`
+- **Workflow imports**: every workflow on this page comes from `@mercurjs/core/workflows`
+
+## Create the attribute
+
+<Steps>
+  <Step title="Run createProductAttributesWorkflow from a route">
+    The workflow takes a list of attributes, each with its values, and returns the created records.
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await createProductAttributesWorkflow(req.scope).run({
-    input: {
-      attributes: [
-        {
-          name: "Material",
-          type: "single_select",
-          is_filterable: true,
-          values: [{ name: "Cotton" }, { name: "Wool" }, { name: "Linen" }],
+    ```ts title="src/api/admin/catalog-import/attributes/route.ts"
+    import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    import { AttributeType } from "@mercurjs/types"
+    import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+    export async function POST(req: MedusaRequest, res: MedusaResponse) {
+      const { result } = await createProductAttributesWorkflow(req.scope).run({
+        input: {
+          attributes: [
+            {
+              name: "Material",
+              type: AttributeType.SINGLE_SELECT,
+              is_filterable: true,
+              values: [{ name: "Cotton" }, { name: "Linen" }],
+            },
+          ],
         },
-      ],
-    },
-  })
+      })
 
-  res.status(201).json({ attribute: result[0] })
-}
-```
+      res.status(201).json({ product_attributes: result })
+    }
+    ```
 
-The workflow creates the attribute, its `ProductAttributeValue` records, and,
-for a `multi_select` axis, the mirror `ProductOption`. It also emits the
-`product-attribute.created` event.
+    Leaving out `product_id` makes the attribute global. The service derives the handle `material` and a handle for each value.
+  </Step>
+  <Step title="Scope it to categories">
+    Pass `category_ids` to link the attribute to product categories in the same run. An attribute with no categories is offered for every product.
 
-<Note>
-  Leaving `product_id` unset creates a **global** attribute reusable across the
-  catalog. Passing a `product_id` creates an **inline** attribute scoped to a
-  single product. See [Global vs inline](/platform/attribute/concepts/global-vs-inline).
-</Note>
+    ```ts
+    await createProductAttributesWorkflow(req.scope).run({
+      input: {
+        attributes: [
+          {
+            name: "Thread count",
+            type: AttributeType.UNIT,
+            category_ids: ["pcat_01JD8Q1234567"],
+          },
+        ],
+      },
+    })
+    ```
 
-## Associate categories
+    A `unit` attribute has no predefined values. Each product gets its own value when you attach the attribute.
+  </Step>
+  <Step title="Add values later">
+    Run `createProductAttributeValuesWorkflow` to add values to an existing select attribute. It takes one `attribute_id` and the new values.
 
-Pass `category_ids` on an attribute to associate it with product categories
-through the category link in the same call:
+    ```ts
+    import { createProductAttributeValuesWorkflow } from "@mercurjs/core/workflows"
 
-```ts
-await createProductAttributesWorkflow(req.scope).run({
-  input: {
-    attributes: [
-      {
-        name: "Thread count",
-        type: "unit",
-        category_ids: ["pcat_bedding"],
+    await createProductAttributeValuesWorkflow(req.scope).run({
+      input: {
+        attribute_id: "pattr_01JD8Q1234567",
+        values: [{ name: "Wool" }, { name: "Silk", rank: 3 }],
       },
-    ],
-  },
-})
+    })
+    ```
+
+    For a variant axis, the workflow also adds the values to the mirror `ProductOption`.
+  </Step>
+</Steps>
+
+## Attach custom data with additional_data
+
+Every catalog workflow accepts `additional_data` and passes it to its completion hook. Register a handler on `productAttributesCreated` to store your own data next to the attribute without forking the workflow.
+
+```ts title="src/workflows/hooks/product-attributes-created.ts"
+import { createProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+createProductAttributesWorkflow.hooks.productAttributesCreated(
+  async ({ attributes, additional_data }, { container }) => {
+    const logger = container.resolve("logger")
+    const source = additional_data?.imported_from
+
+    for (const attribute of attributes) {
+      logger.info(`Attribute ${attribute.id} imported from ${source}`)
+    }
+  }
+)
 ```
 
-## Attach custom data
+Pass the data when you run the workflow, for example `additional_data: { imported_from: "legacy_pim" }`. The workflow also exposes a `validate` hook that runs before anything is written, so you can throw there to reject the input.
+
+## Update or delete an attribute
 
-The workflow accepts an `additional_data` payload passed to its
-`productAttributesCreated` hook, letting you persist marketplace-specific data
-alongside the attribute without forking the workflow.
+`updateProductAttributesWorkflow` takes a `selector` and an `update`. Keep these rules in mind:
+
+- **Type is fixed**: the service throws if `update.type` differs from the current type
+- **Renames reach the option**: changing `name` on an axis also renames its `ProductOption`
+- **Deletes check usage**: `deleteProductAttributesWorkflow` throws `NOT_ALLOWED` while any value is linked to a product
 
 ```ts
-await createProductAttributesWorkflow(req.scope).run({
+import { updateProductAttributesWorkflow } from "@mercurjs/core/workflows"
+
+await updateProductAttributesWorkflow(req.scope).run({
   input: {
-    attributes: [{ name: "Material", type: "single_select" }],
-    additional_data: { imported_from: "legacy-pim" },
+    selector: { id: "pattr_01JD8Q1234567" },
+    update: { name: "Fabric", is_filterable: false },
   },
 })
 ```
+
+The run renames the attribute and turns off its facet flag. The handle stays `material`, because handles are derived only on create.
+
+## Next steps
+
+- [Attach the attribute to a product](/platform/attribute/guides/attach-attributes-to-a-product)
+- [Create a variant axis](/platform/attribute/guides/create-a-variant-axis)
+- [Subscribe to attribute events](/platform/attribute/reference/events)

package/content/platform/attribute/overview.mdx

@@ -1,82 +1,86 @@
 ---
-title: "Attribute"
+title: "Attributes"
 sidebarTitle: "Overview"
-description: "An operator-managed, typed attribute catalog for describing and filtering the shared product catalog."
+description: "Describe the shared catalog with typed attributes, turn them into variant axes, and expose them as storefront filters."
 ---
 
-Use Mercur to define a typed vocabulary for your products, such as colors,
-materials, sizes, capacities, or warranty toggles, and reuse it across the whole
-marketplace.
+Use attributes to give every product in your marketplace the same typed vocabulary, from sizes and materials to capacities and yes/no flags.
 
-The Attribute domain is an operator-managed catalog of typed fields that attach
-to products in the shared master catalog. Attributes describe products
-consistently and drive storefront filters. For variant axes, they generate the
-product variants shoppers pick between. Every attribute is one of five types.
-Each one is either a global catalog entry reused everywhere or an inline field
-scoped to a single product.
+An attribute is a typed field that operators define once and attach to products in the shared master catalog. It describes products the same way across every store, feeds storefront filters, and, when it’s a variant axis, decides which variants a product can have. The Product Attribute module holds the attributes and their values. Links connect them to Medusa’s products, categories, and product options, so a variant axis is a real Medusa `ProductOption` underneath.
+
+<img className="block dark:hidden" src="/images/figures/attribute-overview-light.svg" alt="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it." />
+<img className="hidden dark:block" src="/images/figures/attribute-overview-dark.svg" alt="The global attribute catalog lists Size, Material, Thread count, Gift wrap, and Care with their types, and Size is the one variant axis, backed by the global Medusa product option Size behind it." />
 
 <Note>
-  **Attribute = the `ProductAttribute` entity.** The catalog is owned by the
-  Product Attribute module (`MercurModules.PRODUCT_ATTRIBUTE`, id prefix
-  `pattr`). Products are the shared master catalog. Attributes never belong to a
-  store. Sellers list against master products through offers.
+  The data models are `ProductAttribute` (id prefix `pattr`) and `ProductAttributeValue` (id prefix `pattrval`), resolved with `MercurModules.PRODUCT_ATTRIBUTE` from `@mercurjs/types`. Attributes belong to the catalog, never to a store.
 </Note>
 
 ## Key features
 
-- **Five typed forms:** `single_select`, `multi_select`, `text`, `unit`, and `toggle`, each with its own validation and UI shape.
-- **Variant axes:** a `multi_select` attribute marked `is_variant_axis` mirrors a native Medusa `ProductOption` and generates product variants.
-- **Global or inline:** reuse a global catalog attribute across products, or attach a one-off attribute scoped to a single product.
-- **Storefront filtering:** an `is_filterable` flag exposes an attribute as a shopper-facing facet.
-- **Batch attach:** attach, detach, and update all of a product's attributes through a single engine workflow.
-- **Ordered and governed:** `rank`, `is_active`, and `is_required` control ordering, availability, and required-field enforcement.
+The Product Attribute module covers the full life of a catalog attribute:
+
+- **Five types**: `single_select`, `multi_select`, `text`, `unit`, and `toggle`, each storing its values differently
+- **Variant axes**: a `multi_select` attribute with `is_variant_axis` creates a Medusa `ProductOption` that variants bind to
+- **Global or inline**: define an attribute once for the whole catalog, or create a one-off attribute on a single product
+- **Category scoping**: link an attribute to product categories so it’s offered only for products in them
+- **Storefront filters**: shoppers filter products by axis values, and `is_filterable` tells your storefront which attributes to show as facets
+- **One batch workflow**: attach, detach, and update all of a product’s attributes in a single run
+- **Hooks and events**: catalog workflows expose hooks and emit `product-attribute.*` and `product-attribute-value.*` events
+
+## How it works
+
+An attribute reaches a product in four steps:
+
+1. An operator runs `createProductAttributesWorkflow`. For a variant axis, it also creates a global `ProductOption` with the same values.
+2. A product is created with Mercur’s `createProductsWorkflow`, or edited with `createAndLinkProductAttributesToProductWorkflow`, and picks the attributes and values it uses.
+3. Selected values link to the product. For an axis, the product also gets the option with only the selected subset of values.
+4. Variants bind to the axis option by its title, for example `{ Size: "M" }`, and the storefront filters products by those option values.
 
 ## Get started
 
-Learn how the domain fits together.
+Learn how attributes, values, and axes fit together.
 
 <CardGroup cols={2}>
   <Card title="Attribute types" icon="shapes" href="/platform/attribute/concepts/attribute-types">
-    The five attribute types and the values they hold.
+    The five types and how each one stores its values.
   </Card>
   <Card title="Variant axes" icon="sitemap" href="/platform/attribute/concepts/variant-axes">
-    How `is_variant_axis` mirrors a `ProductOption` and generates variants.
+    How an axis attribute mirrors a Medusa `ProductOption`.
   </Card>
   <Card title="Global vs inline" icon="layer-group" href="/platform/attribute/concepts/global-vs-inline">
-    Catalog-wide attributes, product-scoped attributes, and filtering.
+    Catalog attributes, product-scoped attributes, categories, and filters.
   </Card>
 </CardGroup>
 
 ## Examples
 
-Build against the Attribute domain in your own code.
+Build against attributes in your own server code.
 
 <CardGroup cols={2}>
   <Card title="Create an attribute" icon="plus" href="/platform/attribute/guides/create-an-attribute">
     Run `createProductAttributesWorkflow` from a route or seed script.
   </Card>
   <Card title="Attach to a product" icon="link" href="/platform/attribute/guides/attach-attributes-to-a-product">
-    Attach, detach, and update attributes in one batch call.
+    Attach, detach, and update a product’s attributes in one run.
   </Card>
   <Card title="Create a variant axis" icon="sitemap" href="/platform/attribute/guides/create-a-variant-axis">
-    Generate variants from a `multi_select` axis attribute.
+    Create an axis and build a product’s variants on it.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, links, workflows, service methods, and events for the Attribute
-domain.
+The data models, links, workflows, service methods, and events behind attributes.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/attribute/reference/data-models">
-    The `ProductAttribute` and `ProductAttributeValue` entities.
+    `ProductAttribute` and `ProductAttributeValue`, field by field.
   </Card>
   <Card title="Links" icon="link" href="/platform/attribute/reference/links">
-    How the Attribute domain links to products, categories, and options.
+    Links to products, categories, and product options.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/attribute/reference/workflows">
-    Catalog and product-attachment workflows.
+    Catalog workflows and product attachment workflows.
   </Card>
   <Card title="Service" icon="gear" href="/platform/attribute/reference/service">
     Module service methods for working with records directly.

package/content/platform/attribute/reference/data-models.mdx

@@ -1,56 +1,71 @@
 ---
-title: "Data models"
+title: "Attribute data models"
 sidebarTitle: "Data models"
-description: "The data models owned by the Attribute (Product Attribute) domain."
+description: "Every field on ProductAttribute and ProductAttributeValue, with defaults, nullability, indexes, and relations."
 ---
 
-The Attribute domain is owned by the **Product Attribute module**. This reference
-lists its data models and their fields. For the full module overview, see the
-[Attribute module overview](/platform/attribute/overview).
+The Product Attribute module owns 2 data models: `ProductAttribute` and `ProductAttributeValue`. Both are defined in `packages/core/src/modules/product-attribute/models` and resolved through `MercurModules.PRODUCT_ATTRIBUTE` (`"product_attribute"`). Like every Medusa data model, each also gets `created_at`, `updated_at`, and `deleted_at` timestamps.
 
 ## ProductAttribute
 
-Table `product_attribute`, id prefix `pattr`. A typed catalog attribute.
+A typed attribute in the shared catalog, either global or scoped to one product. Id prefix `pattr`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `name` | text | Searchable |
-| `handle` | text | Nullable; unique when set |
-| `description` | text | Nullable |
-| `type` | enum | `AttributeType`: `single_select`, `multi_select`, `text`, `unit`, `toggle` |
-| `is_required` | boolean | Default `false` |
-| `is_filterable` | boolean | Default `false`; exposes the attribute as a storefront filter |
-| `is_variant_axis` | boolean | Default `false`; `multi_select` axis that generates variants |
-| `rank` | number | Default `0`; ordering |
-| `is_active` | boolean | Default `true` |
-| `created_by` | text | Nullable |
-| `product_id` | text | Nullable; non-null = product-scoped (inline), null = global |
-| `product_option_id` | text | Nullable; FK to the mirror `ProductOption` (axis attributes) |
-| `metadata` | json | Nullable |
-
-Relations: `values` (one-to-many `ProductAttributeValue`, deleted with the
-attribute).
+| `id` | `string` | Primary key, prefixed `pattr` |
+| `handle` | `string \| null` | Unique among non-deleted attributes when set. Derived from `name` on create for global attributes |
+| `name` | `string` | Display name. Searchable. For an axis, also the title of its `ProductOption` |
+| `description` | `string \| null` | Free-form description |
+| `type` | `AttributeType` | One of `single_select`, `multi_select`, `unit`, `toggle`, `text`. Can’t change after create |
+| `is_required` | `boolean` | Default `false`. The remove workflows refuse to detach a required attribute |
+| `is_filterable` | `boolean` | Default `false`. Marks the attribute as a storefront facet |
+| `is_variant_axis` | `boolean` | Default `false`. With `multi_select`, backs the attribute with a `ProductOption` |
+| `rank` | `number` | Default `0`. Sort order |
+| `is_active` | `boolean` | Default `true` |
+| `created_by` | `string \| null` | Id of whoever created the attribute. The built-in routes leave it unset |
+| `product_id` | `string \| null` | `null` for a global attribute, the product’s id for an inline one |
+| `product_option_id` | `string \| null` | Id of the mirror `ProductOption` for an axis attribute |
+| `metadata` | `Record<string, unknown> \| null` | Custom key-value data |
+
+Relations and constraints:
+
+- **`values`**: has many `ProductAttributeValue`, deleted with the attribute
+- **`IDX_product_attribute_handle_unique`**: unique `handle` where `deleted_at IS NULL AND handle IS NOT NULL`
+- **`IDX_product_attribute_type`**: index on `type`
+- **`IDX_product_attribute_product_id`**: index on `product_id` where it’s not null
 
 ## ProductAttributeValue
 
-Table `product_attribute_value`, id prefix `pattrval`. A selectable value that
-belongs to one attribute.
+One selectable value of an attribute, or the stored value of a `text`, `unit`, or `toggle` attribute on a product. Id prefix `pattrval`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `name` | text | The value label |
-| `handle` | text | Nullable; unique per attribute when set |
-| `rank` | number | Default `0`; ordering |
-| `is_active` | boolean | Default `true` |
-| `product_option_value_id` | text | Nullable; FK to the mirror `ProductOptionValue` (axis values) |
-| `metadata` | json | Nullable |
+| `id` | `string` | Primary key, prefixed `pattrval` |
+| `attribute_id` | `string` | Id of the parent `ProductAttribute` |
+| `handle` | `string \| null` | Unique per attribute when set. Derived from `name` on create for values of global select attributes |
+| `name` | `string` | The value label, or the stored content for `text` and `unit` |
+| `rank` | `number` | Default `0`. Sort order within the attribute |
+| `is_active` | `boolean` | Default `true` |
+| `product_option_value_id` | `string \| null` | Id of the mirror `ProductOptionValue` for an axis value |
+| `metadata` | `Record<string, unknown> \| null` | Custom key-value data |
+
+Relations and constraints:
+
+- **`attribute`**: belongs to `ProductAttribute` through `attribute_id`
+- **`IDX_product_attribute_value_handle_unique`**: unique `(attribute_id, handle)` where `deleted_at IS NULL AND handle IS NOT NULL`
+
+## AttributeType enum
+
+`AttributeType` is exported from `@mercurjs/types`:
 
-Relations: `attribute` (belongs to `ProductAttribute` via `attribute_id`).
+| Member | Value |
+| --- | --- |
+| `SINGLE_SELECT` | `"single_select"` |
+| `MULTI_SELECT` | `"multi_select"` |
+| `UNIT` | `"unit"` |
+| `TOGGLE` | `"toggle"` |
+| `TEXT` | `"text"` |
 
 <Note>
-  `product_option_id` on the attribute and `product_option_value_id` on the value
-  are the foreign keys behind the read-only mirror links to Medusa's product
-  options. See [Links](/platform/attribute/reference/links).
+  Neither model stores which products hold a value. That lives in the `product_attribute_value_link` pivot table, described in [Links](/platform/attribute/reference/links).
 </Note>