Skip to main content
The Store API supports storing arbitrary key-value metadata on carts (orders) and line items. Metadata is useful for tracking custom information like gift messages, attribution data, or integration-specific fields.
Metadata is different from metafields. Metadata is simple JSON storage (untyped, no schema), while metafields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use metafields for customer-facing custom attributes.

​
Cart Metadata

You can attach metadata when creating a cart: 
const cart = await client.store.cart.create({
  metadata: {
    utm_source: 'google',
    utm_campaign: 'summer_sale',
    referral_code: 'FRIEND20',
  },
})

​
Order Metadata

Update metadata on an existing order: 
await client.store.orders.update(cart.id, {
  metadata: {
    gift_message: 'Happy Birthday!',
    preferred_delivery: 'morning',
  },
}, { orderToken: cart.token })

​
Line Item Metadata

Attach metadata to individual line items when adding or updating them:

​
When Adding an Item

await client.store.orders.lineItems.create(cart.id, {
  variant_id: 'variant_abc123',
  quantity: 1,
  metadata: {
    personalization: 'John',
    gift_wrap: true,
  },
}, { orderToken: cart.token })

​
When Updating an Item

Updating metadata merges with existing values rather than replacing them: 
await client.store.orders.lineItems.update(cart.id, 'li_xyz789', {
  metadata: {
    personalization: 'Jane', // Updates existing key
    engraving: 'With Love',  // Adds new key
  },
}, { orderToken: cart.token })
Metadata values can be any JSON-serializable type: strings, numbers, booleans, arrays, or nested objects.

​
Metadata Structure

Metadata is stored as a flat JSON object. You can use any keys and values: 
{
  "metadata": {
    "string_value": "hello",
    "number_value": 42,
    "boolean_value": true,
    "nested_object": {
      "key": "value"
    }
  }
}

​
Metadata vs Metafields

MetadataMetafields
StructureUntyped JSONSchema-defined, strongly typed
ValidationNoneType-specific validation
VisibilityWrite-only in Store APIConfigurable (public/private)
Admin UIJSON previewDedicated form fields
Best forIntegration data, tracking, attributionProduct specs, custom fields, customer-facing data
API accessWrite via Store API, read via Admin APIRead/write via both APIs
For more details on metafields, see the Metafields guide.