Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Metadata"
sidebarTitle: "Metadata"
description: "How to store and retrieve custom metadata on carts, orders, and line items"
---
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.
<Note>
Metadata is different from [custom fields](/developer/core-concepts/metafields). Metadata is simple JSON storage (untyped, no schema), while custom fields are structured, typed, and schema-defined. Use metadata for integration data and internal tracking. Use custom fields for customer-facing custom attributes.
</Note>
## Cart Metadata
You can attach metadata when creating a cart:
<CodeGroup>
```typescript SDK
const cart = await client.carts.create({
metadata: {
utm_source: 'google',
utm_campaign: 'summer_sale',
referral_code: 'FRIEND20',
},
})
```
```bash cURL
curl -X POST 'http://localhost:3000/api/v3/store/carts' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"utm_source": "google",
"utm_campaign": "summer_sale",
"referral_code": "FRIEND20"
}
}'
```
</CodeGroup>
## Cart Metadata (Update)
Update metadata on an existing cart:
<CodeGroup>
```typescript SDK
await client.carts.update(cart.id, {
metadata: {
gift_message: 'Happy Birthday!',
preferred_delivery: 'morning',
},
}, { spreeToken: cart.token })
```
```bash cURL
curl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'X-Spree-Token: <order_token>' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"gift_message": "Happy Birthday!",
"preferred_delivery": "morning"
}
}'
```
</CodeGroup>
## Item Metadata
Attach metadata to individual items when adding or updating them:
### When Adding an Item
<CodeGroup>
```typescript SDK
await client.carts.items.create(cart.id, {
variant_id: 'variant_abc123',
quantity: 1,
metadata: {
personalization: 'John',
gift_wrap: true,
},
}, { spreeToken: cart.token })
```
```bash cURL
curl -X POST 'http://localhost:3000/api/v3/store/carts/cart_xxx/items' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'X-Spree-Token: <order_token>' \
-H 'Content-Type: application/json' \
-d '{
"variant_id": "variant_abc123",
"quantity": 1,
"metadata": {
"personalization": "John",
"gift_wrap": true
}
}'
```
</CodeGroup>
### When Updating an Item
Updating metadata **merges** with existing values rather than replacing them:
<CodeGroup>
```typescript SDK
await client.carts.items.update(cart.id, 'li_xyz789', {
metadata: {
personalization: 'Jane', // Updates existing key
engraving: 'With Love', // Adds new key
},
}, { spreeToken: cart.token })
```
```bash cURL
curl -X PATCH 'http://localhost:3000/api/v3/store/carts/cart_xxx/items/li_xyz789' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'X-Spree-Token: <order_token>' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"personalization": "Jane",
"engraving": "With Love"
}
}'
```
</CodeGroup>
<Info>
Metadata values can be any JSON-serializable type: strings, numbers, booleans, arrays, or nested objects.
</Info>
## Metadata Structure
Metadata is stored as a flat JSON object. You can use any keys and values:
```json
{
"metadata": {
"string_value": "hello",
"number_value": 42,
"boolean_value": true,
"nested_object": {
"key": "value"
}
}
}
```
## Metadata vs Custom Fields
Spree has two permanent, complementary systems for custom data — **metadata for machines, custom fields for humans**.
| | Metadata | Custom Fields |
|-|----------|------------|
| **Purpose** | Developer escape hatch — integration IDs, sync state | Merchant-defined structured attributes |
| **Schema** | Schemaless JSON — no definition required | Defined via CustomFieldDefinitions (typed, validated) |
| **Validation** | None | Type-specific validation |
| **Visibility** | Write-only in Store API, readable in Admin API | Configurable (admin-only or public) |
| **Admin UI** | JSON preview | Dedicated form fields |
| **Best for** | Integration data, tracking, attribution, write-and-forget | Product specs, custom attributes, customer-facing data |
| **API access** | Write via Store API, read via Admin API | Read/write via both APIs |
Both systems are here to stay. For more details on custom fields, see the [Custom Fields guide](/developer/core-concepts/metafields).