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
Call them Custom Fields everywhere
Damian Legawiec30619d73174e
diff --git a/docs/api-reference/store-api/metadata.mdx b/docs/api-reference/store-api/metadata.mdxindex 65b3a9e54c..f067ca8942 100644--- a/docs/api-reference/store-api/metadata.mdx+++ b/docs/api-reference/store-api/metadata.mdx@@ -7,7 +7,7 @@ description: "How to store and retrieve custom metadata on carts, orders, and liThe 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 [metafields](/developer/core-concepts/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.+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@@ -158,18 +158,18 @@ Metadata is stored as a flat JSON object. You can use any keys and values:}```-## Metadata vs Metafields+## Metadata vs Custom Fields-Spree has two permanent, complementary systems for custom data — **metadata for machines, metafields for humans**.+Spree has two permanent, complementary systems for custom data — **metadata for machines, custom fields for humans**.-| | Metadata | Metafields |+| | Metadata | Custom Fields ||-|----------|------------|| **Purpose** | Developer escape hatch — integration IDs, sync state | Merchant-defined structured attributes |-| **Schema** | Schemaless JSON — no definition required | Defined via MetafieldDefinitions (typed, validated) |+| **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 metafields, see the [Metafields guide](/developer/core-concepts/metafields).+Both systems are here to stay. For more details on custom fields, see the [Custom Fields guide](/developer/core-concepts/metafields).diff --git a/docs/developer/core-concepts/architecture.mdx b/docs/developer/core-concepts/architecture.mdxindex 6e6aef39c0..2beafd221c 100644--- a/docs/developer/core-concepts/architecture.mdx+++ b/docs/developer/core-concepts/architecture.mdx@@ -5,9 +5,10 @@ description: How Spree fits together — the catalog, the cart, the order, and f## Overview-Spree is a commerce engine you drive through a REST API. It holds the catalog, works out what a customer owes, takes the money, and tracks what was sent. You build the storefront, the mobile app, or the internal tool on top of it.+Spree is a commerce engine you drive through a REST API. It holds the catalog, works out what a customer owes, takes the money, and tracks what was delivered. You build the storefront, the mobile app, Point of Sale or a internal tool on top of it.-There is no built-in storefront you have to accept. Everything a customer-facing app needs is on the Store API, and everything a back office needs is on the Admin API. Both ship as typed TypeScript clients.+There is no built-in storefront you have to accept, however we do provide a [reference one built in Next.js](/developer/storefront/nextjs/quickstart).+Everything a customer-facing app needs is on the Store API, and everything a back office needs is on the Admin API. Both ship as fully typed TypeScript clients.## The shape of a purchase@@ -80,7 +81,7 @@ Three things in that diagram are worth calling out, because they're where Spree**Delivery is described by a profile, not a category.** A [delivery profile](/developer/core-concepts/fulfillments) says how a product travels — physically shipped, or digital — and which locations and methods serve it.-**Stock lives per location.** A variant has a stock level at each [stock location](/developer/core-concepts/inventory), so availability is a real question about real warehouses rather than a single number.+**Stock lives per location.** A variant can have a stock level at each [stock location](/developer/core-concepts/inventory), so availability is a real question about real warehouses rather than a single number.## The two APIs@@ -155,4 +156,4 @@ Two ways in, depending on how you prefer to learn.</Card></CardGroup>-Building a storefront rather than extending the backend? Go straight to the [Store SDK](/developer/sdk/quickstart) or the [Next.js starter](/developer/storefront/nextjs/quickstart).+Building a storefront rather than extending the backend? Go straight to the the [Spree Next.js Storefront](/developer/storefront/nextjs/quickstart).diff --git a/docs/developer/core-concepts/metafields.mdx b/docs/developer/core-concepts/metafields.mdxindex c1648acdcc..7b1cf4bcdb 100644--- a/docs/developer/core-concepts/metafields.mdx+++ b/docs/developer/core-concepts/metafields.mdx@@ -10,7 +10,7 @@ Sooner or later you need to store something Spree doesn't have a field for. A faCustom fields are how you do that without changing the database. You declare a field once — its name, its type, who can see it — and from then on it can be set on any record of that kind, edited in the dashboard, returned by the API, and searched or filtered like any built-in field.<Note>-Custom fields are also known as **metafields** in the dashboard. The API and SDK call them custom fields throughout.+Custom fields are also known as **custom fields** in the dashboard. The API and SDK call them custom fields throughout.</Note>## Definitions and valuesdiff --git a/docs/developer/customization/api.mdx b/docs/developer/customization/api.mdxindex 26af88ac44..9bb1541878 100644--- a/docs/developer/customization/api.mdx+++ b/docs/developer/customization/api.mdx@@ -5,7 +5,7 @@ description: Add new Store API endpoints, customize existing JSON responses withBefore you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](/api-reference/admin-api/endpoints).-For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](/developer/tutorial/admin-api).+For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](/developer/tutorial/model-and-api).## Customizing JSON Responses@@ -35,7 +35,7 @@ Restart the server and the Product API will include your new attribute.### Adding an Association-Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](/developer/tutorial/admin-api) for the full example).+Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](/developer/tutorial/model-and-api) for the full example).Create a serializer for the new model:diff --git a/docs/developer/customization/decorators.mdx b/docs/developer/customization/decorators.mdxindex 9eb78d0845..5ca873ac73 100644--- a/docs/developer/customization/decorators.mdx+++ b/docs/developer/customization/decorators.mdx@@ -562,5 +562,5 @@ end- [Dependencies](/developer/customization/dependencies) - Swap core services with your own- [Admin Navigation](/developer/dashboard/customization/navigation) - Extend admin menu without decorators- [Admin Partials](/developer/dashboard/customization/quickstart) - Extend admin UI without view decorators-- [Extending Core Models Tutorial](/developer/tutorial/model) - Step-by-step guide to connecting custom models with Spree core+- [Extending Core Models Tutorial](/developer/tutorial/model-and-api) - Step-by-step guide to connecting custom models with Spree core- [Customization Overview](/developer/customization/quickstart) - General customization patternsdiff --git a/docs/developer/customization/metadata.mdx b/docs/developer/customization/metadata.mdxindex edb43fbcf4..fa0582e949 100644--- a/docs/developer/customization/metadata.mdx+++ b/docs/developer/customization/metadata.mdx@@ -6,12 +6,12 @@ title: MetadataMetadata provides simple, unstructured key-value storage on Spree resources — similar to [Stripe's metadata](https://docs.stripe.com/api/metadata). It's ideal for storing integration IDs, tracking data, or any arbitrary information that doesn't need validation or admin UI.-Metadata is a **permanent, first-class system** in Spree. It is designed to coexist alongside [Metafields](/developer/core-concepts/metafields) (structured, typed, admin-managed). The two systems serve different purposes and are not interchangeable — think of it as **metadata for machines, metafields for humans**.+Metadata is a **permanent, first-class system** in Spree. It is designed to coexist alongside [Custom Fields](/developer/core-concepts/metafields) (structured, typed, admin-managed). The two systems serve different purposes and are not interchangeable — think of it as **metadata for machines, custom fields for humans**.Metadata is **write-only** in the Store API — you can set it when creating or updating resources, but it is never returned in Store API responses. It is visible in Admin API responses for administrative use.<Info>-For structured, type-safe custom attributes with admin UI support, use [Metafields](/developer/core-concepts/metafields) instead.+For structured, type-safe custom attributes with admin UI support, use [Custom Fields](/developer/core-concepts/metafields) instead.</Info>## Store API@@ -188,14 +188,14 @@ Metadata updates use **merge semantics** — existing keys are preserved, new ke{ "source": "mobile_app", "campaign": "winter", "new_key": "value" }```-## Metadata vs Metafields+## Metadata vs Custom FieldsSpree has two permanent, complementary systems for custom data. They are not interchangeable and neither is going away.-| | Metadata | [Metafields](/developer/core-concepts/metafields) |+| | Metadata | [Custom Fields](/developer/core-concepts/metafields) ||---|---|---|| **Purpose** | Developer escape hatch — integration data, sync state, ad-hoc flags | Merchant-defined structured attributes with admin UI |-| **Schema** | Schemaless JSON — no definition required | Defined via MetafieldDefinitions (typed, validated) |+| **Schema** | Schemaless JSON — no definition required | Defined via CustomFieldDefinitions (typed, validated) || **Validation** | None — accepts any JSON-serializable data | Type-specific (text, number, boolean, rich text, JSON) || **Visibility** | Write-only in Store API, readable in Admin API | Configurable (front-end, back-end, both) || **Admin UI** | JSON preview only | Dedicated management forms |@@ -210,7 +210,7 @@ Spree has two permanent, complementary systems for custom data. They are not int- Any write-and-forget data that only needs to be read by backend systems- Syncing state with external integrations (webhooks, ETL pipelines)-### When to use metafields+### When to use custom fields- Custom product specifications shown to customers (material, dimensions, certifications)- Admin-managed fields with validation and type safety@@ -235,7 +235,7 @@ The Store API currently supports writing metadata on:The `public_metadata` column was never exposed in Store API responses and in practice served the same purpose as `private_metadata`. Calling `public_metadata=` emits a deprecation warning.-Always use the single `metadata` accessor for all schemaless key-value storage. If you need data visible to customers on the storefront, use [Metafields](/developer/core-concepts/metafields) instead.+Always use the single `metadata` accessor for all schemaless key-value storage. If you need data visible to customers on the storefront, use [Custom Fields](/developer/core-concepts/metafields) instead.```ruby# Deprecated — use `metadata` instead@@ -244,6 +244,6 @@ order.public_metadata = { 'gift_message' => 'Happy Birthday!' }# Use metadata for internal storageorder.metadata = { 'gift_message' => 'Happy Birthday!' }-# Use metafields for customer-visible structured data-order.set_metafield('custom.gift_message', 'Happy Birthday!')+# Use custom fields for customer-visible structured data+order.set_custom_field('custom.gift_message', 'Happy Birthday!')```diff --git a/docs/developer/getting-started/quickstart.mdx b/docs/developer/getting-started/quickstart.mdxindex fb927d7dda..3554c900cf 100644--- a/docs/developer/getting-started/quickstart.mdx+++ b/docs/developer/getting-started/quickstart.mdx@@ -28,10 +28,10 @@ description: "Install Spree Commerce locally, run your first store, and deploy i```my-store/-├── server/ # The Spree API — models, endpoints, jobs, specs+├── server/ # The Spree API├── apps/-│ ├── dashboard/ # Admin dashboard (React)-│ ├── seller-dashboard/ # Seller panel, for marketplaces (React)+│ ├── dashboard/ # Admin dashboard (Vite/React)+│ ├── seller-dashboard/ # Seller panel, for marketplaces (Vite/React)│ └── storefront/ # Next.js storefront (if selected)├── .env # Ports, secrets and service URLs├── .spree/ # CLI credentials — gitignored, created on first run@@ -42,10 +42,6 @@ my-store/└── README.md # How to run everything```-**`server/` is the only part that is Spree's.** You own the apps under `apps/` outright — they are ordinary Vite and Next.js projects that talk to the API over HTTP, so you can restyle, restructure or replace them without forking anything.--Each app carries its own instructions: `server/CLAUDE.md`, `apps/dashboard/AGENTS.md` and so on. Read the one for the directory you are working in — that is also what a coding agent picks up.-## Using the Spree CLIProjects scaffolded with `create-spree-app` include [`@spree/cli`](/developer/cli/quickstart) for managing the backend and calling the Admin API. Because it's a project dependency, run it with `npx` (or any package-manager script):@@ -72,7 +68,7 @@ See the [Spree CLI guide](/developer/cli/quickstart) for all commands and the [AThe catalog, the cart, the order and fulfillment — what each one is for, and the two APIs you build against. Twenty minutes here saves a lot of guessing later, and it ends by pointing you at whichever path suits you.</Card>-In a hurry? Jump straight to the [tutorial](/developer/tutorial/introduction) to build a feature end to end, the [Next.js Storefront](/developer/storefront/nextjs/quickstart) to put a storefront in front of it, or the [CLI reference](/developer/create-spree-app/quickstart) for what the scaffold generated.+In a hurry? Jump straight to the [tutorial](/developer/tutorial/introduction) to build a feature end to end, the [Next.js Storefront](/developer/storefront/nextjs/quickstart) to put a storefront in front of it, or the [API reference](/api-reference/admin-api/introduction) to see what you can do with the Admin API.<Tip>Using an AI coding agent? Run `npx skills add spree/agent-skills` in your new project — it teaches your agent the customization patterns before you write a line of code. See [Agentic Development](/developer/agentic/overview).diff --git a/docs/developer/how-to/custom-promotion.mdx b/docs/developer/how-to/custom-promotion.mdxindex 895f4e5d4a..5ddd1402d8 100644--- a/docs/developer/how-to/custom-promotion.mdx+++ b/docs/developer/how-to/custom-promotion.mdx@@ -154,7 +154,7 @@ module Spreeprivatedef matches_brand?(line_item)- brand = line_item.product.get_metafield('details.brand')&.value+ brand = line_item.product.get_custom_field('details.brand')&.valuepreferred_brand_names.include?(brand)endenddiff --git a/docs/developer/how-to/custom-search-provider.mdx b/docs/developer/how-to/custom-search-provider.mdxindex 4fb8813d6e..2d15beee7a 100644--- a/docs/developer/how-to/custom-search-provider.mdx+++ b/docs/developer/how-to/custom-search-provider.mdx@@ -230,9 +230,9 @@ Background jobs (`IndexJob`, `RemoveJob`) fire on `after_commit` when `indexing_Always use prefixed IDs (`ctg_abc`, `prod_xyz`, `optval_abc`) when indexing. Never use raw database IDs — Spree supports UUID primary keys.-### Metafield search schema+### Custom Field search schema-Product metafields marked `searchable` / `sortable` on `MetafieldDefinition` are projected through `Spree::SearchProvider::MetafieldSchema` — shared by providers and `ProductPresenter`. Toggle participation with definition flags; run `rake spree:search:reindex` after changes when using Meilisearch.+Product custom fields marked `searchable` / `sortable` on `CustomFieldDefinition` are projected through `Spree::SearchProvider::CustomFieldSchema` — shared by providers and `ProductPresenter`. Toggle participation with definition flags; run `rake spree:search:reindex` after changes when using Meilisearch.Document shaping for `cf_*` fields stays on `search_product_presenter` — the only search-related dependency.diff --git a/docs/developer/how-to/custom-stock-splitter.mdx b/docs/developer/how-to/custom-stock-splitter.mdxindex 8be9461a86..59d4898856 100644--- a/docs/developer/how-to/custom-stock-splitter.mdx+++ b/docs/developer/how-to/custom-stock-splitter.mdx@@ -170,12 +170,12 @@ end### Step 4 (optional): Add a Variant-side Predicate-The example above relies on `variant.refrigerated?`. In a real plugin you'd back that with a [Custom Field](/developer/core-concepts/metafields) on `Spree::Variant` — say a boolean metafield with key `refrigerated` — and define the predicate as a thin reader:+The example above relies on `variant.refrigerated?`. In a real plugin you'd back that with a [Custom Field](/developer/core-concepts/metafields) on `Spree::Variant` — say a boolean custom field with key `refrigerated` — and define the predicate as a thin reader:```ruby app/models/spree/variant_decorator.rbSpree::Variant.class_eval dodef refrigerated?- metafields.find_by(namespace: 'logistics', key: 'refrigerated')&.value == 'true'+ custom fields.find_by(namespace: 'logistics', key: 'refrigerated')&.value == 'true'endend```diff --git a/docs/developer/sdk/admin/extending.mdx b/docs/developer/sdk/admin/extending.mdxindex 146b70bbea..c05a49cf59 100644--- a/docs/developer/sdk/admin/extending.mdx+++ b/docs/developer/sdk/admin/extending.mdx@@ -66,5 +66,5 @@ The SDK transforms `filter`/`sort` into the Ransack-flavored query string the Ad## See also- The [Store SDK extending guide](/developer/sdk/extending) covers the same pattern for storefront endpoints — the API is identical, only the base path (`/api/v3/store`) and auth header differ.-- The [API](/developer/tutorial/admin-api) and [SDK](/developer/tutorial/storefront) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.+- The [API](/developer/tutorial/model-and-api) and [SDK](/developer/tutorial/storefront) tutorials walk through creating new Spree endpoints end-to-end (Rails controller, serializer, TypeScript types). Everything they show for the Store API applies equivalently for the Admin API.- For building dashboard UI on top of your custom endpoint, see the [Dashboard](/developer/dashboard/overview) section — start with [Customization Quickstart](/developer/dashboard/customization/quickstart) for in-app changes or [Plugin Overview](/developer/dashboard/plugins/overview) for redistributable packages.diff --git a/docs/developer/sdk/admin/quickstart.mdx b/docs/developer/sdk/admin/quickstart.mdxindex 55cd0a0d57..66e00e0121 100644--- a/docs/developer/sdk/admin/quickstart.mdx+++ b/docs/developer/sdk/admin/quickstart.mdx@@ -79,5 +79,5 @@ const page: PaginatedResponse<Order> = await client.orders.list()</CardGroup><Tip>- Adding your own resources? The [`spree generate api_resource`](/developer/tutorial/admin-api) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](/developer/sdk/extending) shows how to call custom endpoints from the SDK.+ Adding your own resources? The [`spree generate api_resource`](/developer/tutorial/model-and-api) generator scaffolds Admin API endpoints (model, serializers, controllers, specs) in one command, and the [extending guide](/developer/sdk/extending) shows how to call custom endpoints from the SDK.</Tip>diff --git a/docs/developer/sdk/admin/resources.mdx b/docs/developer/sdk/admin/resources.mdxindex 17fa7dcc5c..81279803d3 100644--- a/docs/developer/sdk/admin/resources.mdx+++ b/docs/developer/sdk/admin/resources.mdx@@ -127,4 +127,4 @@ await client.customFields('Spree::Product', 'prod_xxx').list()## Adding your own resources-The resource map grows with your store. The [`spree generate api_resource`](/developer/tutorial/admin-api) generator scaffolds new Admin API endpoints (model, serializers, controllers, routes, specs) in one command — then call them from the SDK with a [custom fetch or raw request](/developer/sdk/extending), or generate a typed client for them.+The resource map grows with your store. The [`spree generate api_resource`](/developer/tutorial/model-and-api) generator scaffolds new Admin API endpoints (model, serializers, controllers, routes, specs) in one command — then call them from the SDK with a [custom fetch or raw request](/developer/sdk/extending), or generate a typed client for them.diff --git a/docs/developer/sdk/configuration.mdx b/docs/developer/sdk/configuration.mdxindex 3b7ea2fe35..b84ea44fd5 100644--- a/docs/developer/sdk/configuration.mdx+++ b/docs/developer/sdk/configuration.mdx@@ -156,7 +156,7 @@ All types are exported as unprefixed names (e.g., `Product`, `Order`). Legacy `S- `OptionType` - Option type (e.g., Size, Color)- `OptionValue` - Option value (e.g., Small, Red)- `DigitalLink` - Digital download link-- `Metafield` - Custom metafield data+- `Custom Field` - Custom custom field data### Wishlist Types- `Wishlist` - Wishlistdiff --git a/docs/developer/sdk/extending.mdx b/docs/developer/sdk/extending.mdxindex 8bb92735d2..5b1750502e 100644--- a/docs/developer/sdk/extending.mdx+++ b/docs/developer/sdk/extending.mdx@@ -30,4 +30,4 @@ const nike = await client.request<Brand>('GET', '/brands/nike')`client.request` uses the same auth headers, retry logic, and locale/currency defaults as `client.products.list()` or any other built-in resource.-For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [API](/developer/tutorial/admin-api) and [SDK](/developer/tutorial/storefront) tutorials.+For a complete walkthrough — creating the API endpoints on the backend, defining TypeScript types, filtering, and expanding associations — see the [API](/developer/tutorial/model-and-api) and [SDK](/developer/tutorial/storefront) tutorials.diff --git a/docs/docs.json b/docs/docs.jsonindex f5c55ce3d1..911758cc7e 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -787,7 +787,7 @@]},{- "group": "Next.js Starter",+ "group": "Next.js Storefront","pages": ["developer/storefront/nextjs/quickstart","developer/storefront/nextjs/architecture",@@ -2083,7 +2083,7 @@{"item": "Building a Storefront","icon": "store",- "description": "Next.js, custom frontend, or Rails engine",+ "description": "Use Spree Storefront or build your own","groups": [{"group": "Next.js Storefront",diff --git a/docs/images/store_setup.png b/docs/images/store_setup.pngnew file mode 100644index 0000000000..97e005673eBinary files /dev/null and b/docs/images/store_setup.png differdiff --git a/docs/user/how-to/multi-currency-pricing.mdx b/docs/user/how-to/multi-currency-pricing.mdxindex 4e5b23f93e..b738be16be 100644--- a/docs/user/how-to/multi-currency-pricing.mdx+++ b/docs/user/how-to/multi-currency-pricing.mdx@@ -64,7 +64,7 @@ Repeat this process for every product you want to make available to German custoOnce your market and product prices are set up, verify the setup by visiting your storefront.-1. Look for the market switcher in your storefront's navigation. If you're using the Spree Next.js starter storefront, this appears in the navigation bar.+1. Look for the market switcher in your storefront's navigation. If you're using the Spree Next.js Storefront, this appears in the navigation bar.2. Switch to **Germany / EUR**3. Confirm that product prices are now displayed in EURdiff --git a/docs/user/how-to/multi-region-pricing.mdx b/docs/user/how-to/multi-region-pricing.mdxindex 0eea9bf5d9..44a4f2f8d9 100644--- a/docs/user/how-to/multi-region-pricing.mdx+++ b/docs/user/how-to/multi-region-pricing.mdx@@ -85,7 +85,7 @@ Repeat this entire process to create a second price list for Spain — name it `Once your markets and price lists are active, verify that the correct prices appear for each region.-1. Visit your storefront and look for the market switcher in the navigation. If you're using the Spree Next.js starter storefront, this appears in the navigation bar.+1. Visit your storefront and look for the market switcher in the navigation. If you're using the Spree Next.js Storefront, this appears in the navigation bar.2. Switch to **France / EUR** and note the price shown for a product you included in the France price list.3. Switch to **Spain / EUR** and confirm the price changes to reflect the Spain price list.4. Switch back to **Germany / EUR** and confirm the base EUR price is shown (since Germany has no regional price list).diff --git a/docs/user/manage-products/import-products.mdx b/docs/user/manage-products/import-products.mdxindex f0a582250f..2aa063c1b3 100644--- a/docs/user/manage-products/import-products.mdx+++ b/docs/user/manage-products/import-products.mdx@@ -80,7 +80,7 @@ To do so:<Warning>When updating products in bulk, make sure to keep the slug exactly the same for each existing product. The slug is the unique identifier used during import - changing it will cause Spree to treat the row as a new product and create a duplicate record.</Warning>-This is the safest and most efficient way to make large-scale updates to product data such as pricing, descriptions, inventory, or metafields.+This is the safest and most efficient way to make large-scale updates to product data such as pricing, descriptions, inventory, or custom fields.<Note>If your store sells in multiple currencies, your exported file will include additional price-only rows for each currency. See [<u>Multi-Currency Import/Export</u>](https://spreecommerce.org/docs/user/manage-products/multi-currency-import-export) for details on how these rows work.</Note>diff --git a/docs/user/manage-products/multi-currency-import-export.mdx b/docs/user/manage-products/multi-currency-import-export.mdxindex d2bb5ddd5d..91bc10626f 100644--- a/docs/user/manage-products/multi-currency-import-export.mdx+++ b/docs/user/manage-products/multi-currency-import-export.mdx@@ -19,7 +19,7 @@ These additional rows are called **price-only rows**. They contain a smaller set- **Compare At Price** - The original/crossed-out price, if applicable- **Currency** - The currency code for this row (e.g., `EUR`, `GBP`)-All other product fields (name, description, taxons, metafields, etc.) are left blank in price-only rows — they're intentionally omitted because those fields are already handled by the primary row.+All other product fields (name, description, taxons, custom fields, etc.) are left blank in price-only rows — they're intentionally omitted because those fields are already handled by the primary row.## Exporting Multi-Currency Prices@@ -55,7 +55,7 @@ To import your updated file, navigate to the **Products** tab and click **Import3. Click **Create** to proceed to the field mapping step.4. Review the field mapping and adjust any columns that weren't matched automatically, then click **Continue** to submit.-Spree will automatically detect which rows are full product rows and which are price-only rows. For price-only rows, it will update only the pricing data for the specified currency — it won't overwrite your product descriptions, taxons, or metafields.+Spree will automatically detect which rows are full product rows and which are price-only rows. For price-only rows, it will update only the pricing data for the specified currency — it won't overwrite your product descriptions, taxons, or custom fields.<Note>You can import pricing updates for a single currency without including rows for other currencies. Just remove any rows you don't want to update before importing.</Note>diff --git a/docs/user/manage-products/product-import-file-template.mdx b/docs/user/manage-products/product-import-file-template.mdxindex 400ef7731f..8bc3bf03d9 100644--- a/docs/user/manage-products/product-import-file-template.mdx+++ b/docs/user/manage-products/product-import-file-template.mdx@@ -50,4 +50,4 @@ For an example of **how to structure multi-variant products**, please download t| category1 | The 1st [category](https://spreecommerce.org/docs/user/products/categories) to which the product should be assigned|| category2 | The 2nd category to which the product should be assigned || category3 | The 3rd category to which the product should be assigned |-| metafield.namespace.key | The value for the product metafield [namespace.key](https://spreecommerce.org/docs/user/settings/metafields)|+| custom field.namespace.key | The value for the product custom field [namespace.key](https://spreecommerce.org/docs/user/settings/metafields)|diff --git a/docs/user/manage-products/product-metafields.mdx b/docs/user/manage-products/product-metafields.mdxindex 8f967cc54d..9cc2add300 100644--- a/docs/user/manage-products/product-metafields.mdx+++ b/docs/user/manage-products/product-metafields.mdx@@ -1,15 +1,15 @@----title: "Product Metafields"-description: "Learn how to use product metafields in Spree Commerce to enrich your product data."+title: "Product Custom Fields"+description: "Learn how to use product custom fields in Spree Commerce to enrich your product data."----Product Metafields allow you to add custom attributes to products beyond the default fields included in Spree. Whether you want to display additional product specifications on the storefront, store internal merchandising notes, or support advanced integrations, metafields give you complete flexibility directly from the admin dashboard.+Product Custom Fields allow you to add custom attributes to products beyond the default fields included in Spree. Whether you want to display additional product specifications on the storefront, store internal merchandising notes, or support advanced integrations, custom fields give you complete flexibility directly from the admin dashboard.-Unlike legacy product properties, metafields are structured, scalable, and work seamlessly with imports, APIs, and storefront display settings.+Unlike legacy product properties, custom fields are structured, scalable, and work seamlessly with imports, APIs, and storefront display settings.-## Why Use Product Metafields?+## Why Use Product Custom Fields?-Product metafields are ideal when you need to:+Product custom fields are ideal when you need to:- Add **technical specifications** (e.g., voltage, dimensions, fabric composition)- Display **care instructions**@@ -21,21 +21,21 @@ Product metafields are ideal when you need to:- Power custom storefront sections- Support third-party integrations-Because metafields can be created and managed entirely from the dashboard, they reduce development time and eliminate the need for database changes or code deployments.+Because custom fields can be created and managed entirely from the dashboard, they reduce development time and eliminate the need for database changes or code deployments.-## How to Create a Product Metafield+## How to Create a Product Custom Field-To create a new product metafield, navigate to **Settings → Metafield Definitions**.+To create a new product custom field, navigate to **Settings → Custom Field Definitions**.-+-Click **New Metafield Definition** to open the metafield creation form.+Click **New Custom Field Definition** to open the custom field creation form.-+Complete the form fields as described below.-## **Metafield Definition Fields**+## **Custom Field Definition Fields**### **Name**@@ -48,14 +48,14 @@ Example:### **Namespace**-Used to group metafields and avoid naming conflicts.+Used to group custom fields and avoid naming conflicts.- We recommend using something like **custom** for merchant-defined product fields.- Avoid using reserved model names like **product**, **variant**, or **order**.### **Key**-The unique identifier for the metafield (combined with the namespace).+The unique identifier for the custom field (combined with the namespace).Example:@@ -65,13 +65,13 @@ Example:### **Resource**-For product metafields, select **Product**.+For product custom fields, select **Product**.-To learn more about creating metafields for other resources, see [<u>Metafields</u>](https://spreecommerce.org/docs/user/settings/metafields).+To learn more about creating custom fields for other resources, see [<u>Custom Fields</u>](https://spreecommerce.org/docs/user/settings/metafields).## **Choosing the Right Data Type**-Each metafield must have a type. Selecting the appropriate type ensures your data is structured correctly.+Each custom field must have a type. Selecting the appropriate type ensures your data is structured correctly.### **Short Text**@@ -135,47 +135,47 @@ Examples:## Display Settings-Choose where the metafield should appear:+Choose where the custom field should appear:- **Admin Only** - Internal use (e.g., supplier notes, internal margin classification)- **Admin & Storefront** - Visible to customers on product pages-If displayed on the storefront, metafields can be used within your theme to enhance the Product Detail Page (PDP).+If displayed on the storefront, custom fields can be used within your theme to enhance the Product Detail Page (PDP).-## Adding Product Metafield Values+## Adding Product Custom Field ValuesOnce the definition is created, you can assign values to individual products.### Adding Values Individually-+-To add metafield values for individual products:+To add custom field values for individual products:1. Navigate to **Products**2. Open the product you want to update3. Click the **three-dot menu** in the top-right corner-4. Select **Metafields** to open the metafields form+4. Select **Custom Fields** to open the custom fields form5. Enter the desired values6. Click **Save**This method is ideal for updating a small number of products.-### Updating Product Metafields in Bulk+### Updating Product Custom Fields in Bulk-You can also import metafields via CSV.+You can also import custom fields via CSV.#### Step 1: Add a Column to the product CSV fileUse this format:-**metafield.namespace.key**+**custom field.namespace.key**Example:-- **metafield.custom.material**-- **metafield.custom.care_instructions**-- **metafield.custom.sustainability_score**+- **custom field.custom.material**+- **custom field.custom.care_instructions**+- **custom field.custom.sustainability_score**#### Step 2: Add Values Per Product Row@@ -193,9 +193,9 @@ Please refer to the following support articles for more information about produc- [<u>Import Product</u>](https://spreecommerce.org/docs/user/manage-products/import-products)- [<u>Product Import Template</u>](https://spreecommerce.org/docs/user/manage-products/product-import-file-template)-## Real-World Product Metafield Examples+## Real-World Product Custom Field Examples-Here are some practical examples of how merchants use product metafields:+Here are some practical examples of how merchants use product custom fields:### Apparel@@ -235,8 +235,8 @@ Here are some practical examples of how merchants use product metafields:## Replacing Product Properties-Product Properties are no longer supported in the latest version of Spree. Product Metafields provide a more flexible, scalable, and structured solution for managing custom product attributes.+Product Properties are no longer supported in the latest version of Spree. Product Custom Fields provide a more flexible, scalable, and structured solution for managing custom product attributes.-If you previously relied on properties for product enrichment, metafields are now the recommended approach.+If you previously relied on properties for product enrichment, custom fields are now the recommended approach.-Product metafields give you the flexibility to tailor your product data model to your business - without relying on developers - while keeping your catalog structured, scalable, and integration-ready.+Product custom fields give you the flexibility to tailor your product data model to your business - without relying on developers - while keeping your catalog structured, scalable, and integration-ready.diff --git a/docs/user/migration/migrate-from-shopify.mdx b/docs/user/migration/migrate-from-shopify.mdxindex 3ae4b10a5c..3440c92c77 100644--- a/docs/user/migration/migrate-from-shopify.mdx+++ b/docs/user/migration/migrate-from-shopify.mdx@@ -57,8 +57,8 @@ Spree's import system lets you map CSV columns to Spree fields during the import| `Option2 Value` | `option2_value` | Second option value || `Option3 Name` | `option3_name` | Third option name || `Option3 Value` | `option3_value` | Third option value |-| `Cost per item` | — | Not directly imported, can be set via metafields |-| `Vendor` | — | Can be imported as a metafield or tag |+| `Cost per item` | — | Not directly imported, can be set via custom fields |+| `Vendor` | — | Can be imported as a custom field or tag || `Product Category` | `category1` | Requires format adjustment (see below) |### Step-by-Step Import@@ -143,13 +143,13 @@ Shopify's `Variant Grams` column is **always in grams** regardless of the `VariaThese Shopify-specific columns don't have direct Spree equivalents and can be safely skipped:-- `Vendor` — consider importing as a tag or metafield+- `Vendor` — consider importing as a tag or custom field- `Published` — use `status` instead (`active` = published)- `Variant Inventory Tracker` — Spree handles inventory tracking differently- `Variant Fulfillment Service` — not applicable- `Variant Requires Shipping` — controlled by shipping categories in Spree- `Variant Taxable` — controlled by tax categories in Spree-- `Variant Barcode` — can be added as a metafield+- `Variant Barcode` — can be added as a custom field- `Gift Card` — Spree has its own gift card system- `Google Shopping / *` — not imported (legacy Shopify columns)@@ -174,7 +174,7 @@ Shopify's customer CSV maps closely to Spree's customer import schema:| `Default Address Province Code` | `province_code` | ISO state/province code (e.g., `NY`, `CA`) || `Default Address Country Code` | `country_code` | ISO country code (e.g., `US`, `GB`) || `Default Address Zip` | `zip` | Postal/zip code |-| `Note` | — | Not directly imported, can be added as a metafield |+| `Note` | — | Not directly imported, can be added as a custom field || `Tax Exempt` | — | Not directly imported || `Total Spent` | — | Read-only in Shopify, not imported || `Total Orders` | — | Read-only in Shopify, not imported |diff --git a/docs/user/products/creating-products.mdx b/docs/user/products/creating-products.mdxindex 2510cde67a..2111f94eb6 100644--- a/docs/user/products/creating-products.mdx+++ b/docs/user/products/creating-products.mdx@@ -168,11 +168,11 @@ If your shipping methods rely on product size or weight, this section is criticaYou can change the default unit system (metric vs imperial) in **Settings → Store Details → Standards & Formats**.</Note>-## Product Metafields+## Product Custom Fields-Product Metafields let you add custom data fields to a product beyond Spree's built-in fields — useful for technical specs, care instructions, supplier notes, or anything else specific to your catalog. For example, a clothing product might have a **Material** metafield set to "100% Organic Cotton," or an electronics product might have a **Voltage** metafield set to "110–240V."+Product Custom Fields let you add custom data fields to a product beyond Spree's built-in fields — useful for technical specs, care instructions, supplier notes, or anything else specific to your catalog. For example, a clothing product might have a **Material** custom field set to "100% Organic Cotton," or an electronics product might have a **Voltage** custom field set to "110–240V."-See [<u>Product Metafields</u>](/user/manage-products/product-metafields) to learn how to create metafield definitions and add values to your products.+See [<u>Product Custom Fields</u>](/user/manage-products/product-metafields) to learn how to create custom field definitions and add values to your products.## Taxdiff --git a/docs/user/settings/metafields.mdx b/docs/user/settings/metafields.mdxindex 4a88d8712b..7e58d4b4d1 100644--- a/docs/user/settings/metafields.mdx+++ b/docs/user/settings/metafields.mdx@@ -1,41 +1,41 @@----title: "Metafield Definitions"-description: "Define and manage custom metafields in Spree to attach extra structured data to products, orders, and other store objects without code changes."+title: "Custom Field Definitions"+description: "Define and manage custom custom fields in Spree to attach extra structured data to products, orders, and other store objects without code changes."----Metafields in Spree allow you to attach custom data to nearly any object in your store - without needing to write a single line of code or modify the database.+Custom Fields in Spree allow you to attach custom data to nearly any object in your store - without needing to write a single line of code or modify the database.-From product materials to internal order notes, metafields give you the flexibility to store, manage, and display extra information that doesn't come out of the box. This reduces reliance on developer deployments, makes experimentation easier, and enables faster iteration directly from the admin dashboard.+From product materials to internal order notes, custom fields give you the flexibility to store, manage, and display extra information that doesn't come out of the box. This reduces reliance on developer deployments, makes experimentation easier, and enables faster iteration directly from the admin dashboard.-## Creating a New Metafield+## Creating a New Custom Field-To create a metafield definition go to **Settings → Metafield Definitions**+To create a custom field definition go to **Settings → Custom Field Definitions**-+-Here you’ll see a list of all existing metafield definitions in your store.+Here you’ll see a list of all existing custom field definitions in your store.-To add a new one, click **New Metafield Definition** in the top right corner.+To add a new one, click **New Custom Field Definition** in the top right corner.-+Fill out the form with the required details:- **Name** - this is the display name for the field, shown in the dashboard and/or storefront-- **Namespace** - used to group metafields and avoid naming conflicts+- **Namespace** - used to group custom fields and avoid naming conflicts- We recommend using something like “custom” for internal or merchant-defined fields- Avoid using common Spree model names like product, order, or variant as these may conflict with existing integrations- **Key** - the unique identifier for the field, combined with the namespace- e.g.: custom.material, custom.internal_note-- **Resource** - choose the object the metafield applies to (see full list below)+- **Resource** - choose the object the custom field applies to (see full list below)- **Type** - the format of data the field should accept (see examples below)- **Display on** - choose whether this field appears in the Admin only, or Admin and Storefront.### Supported Resources-+-You can define metafields for nearly any data object in Spree:+You can define custom fields for nearly any data object in Spree:- **Address** - e.g., delivery instructions- **Asset** - e.g., alt text or copyright@@ -71,9 +71,9 @@ You can define metafields for nearly any data object in Spree:### Supported Data Types-+-Each metafield must be assigned a **type**, which determines the format of the stored value. Choosing the right type helps keep data structured, valid, and useful across the storefront and admin.+Each custom field must be assigned a **type**, which determines the format of the stored value. Choosing the right type helps keep data structured, valid, and useful across the storefront and admin.- **Short Text** - for single-line strings, e.g., "Cotton" or "Blue"- **Long Text** - multi-line content, e.g., care instructions@@ -82,34 +82,34 @@ Each metafield must be assigned a **type**, which determines the format of the s- **Boolean** - true/false flags, e.g., “Is this product fragile?” = true- **JSON** - for structured data or multiple related attributes-## Adding Metafield Values+## Adding Custom Field Values-Once your metafield definition has been created, you can enter values in a few different ways:+Once your custom field definition has been created, you can enter values in a few different ways:### Individually in the Admin DashboardFirst, navigate to the relevant resource (e.g., Product, Order, Shipment).-+-Click the **three-dot menu** in the top right corner and select **Metafields** from the dropdown.+Click the **three-dot menu** in the top right corner and select **Custom Fields** from the dropdown.-+Enter the desired values in the form and click **Save** to finalized your changes.-+-This works for any individual resource type and is perfect for adding or editing a few metafields manually.+This works for any individual resource type and is perfect for adding or editing a few custom fields manually.### In Bulk (Products Only)-Product metafields can also be imported or updated in bulk by:+Product custom fields can also be imported or updated in bulk by:-1. Adding columns to your CSV file using this format: metafield.namespace.key (e.g. metafield.custom.material)+1. Adding columns to your CSV file using this format: custom field.namespace.key (e.g. custom field.custom.material)2. Entering the desired values for each product row.3. Importing the file when uploading a new product catalog-You can also update your existing catalog by exporting the product file, updating it as described above, and then reimporting it to apply metafield updates+You can also update your existing catalog by exporting the product file, updating it as described above, and then reimporting it to apply custom field updatesThis is ideal for large-scale changes across multiple products, especially when onboarding a large catalog.diff --git a/docs/v5/user/how-to/multi-currency-pricing.mdx b/docs/v5/user/how-to/multi-currency-pricing.mdxindex f35ea90959..f42e09e972 100644--- a/docs/v5/user/how-to/multi-currency-pricing.mdx+++ b/docs/v5/user/how-to/multi-currency-pricing.mdx@@ -65,7 +65,7 @@ Repeat this process for every product you want to make available to German custoOnce your market and product prices are set up, verify the setup by visiting your storefront.-1. Look for the market switcher in your storefront's navigation. If you're using the Spree Next.js starter storefront, this appears in the navigation bar.+1. Look for the market switcher in your storefront's navigation. If you're using the Spree Next.js Storefront, this appears in the navigation bar.2. Switch to **Germany / EUR**3. Confirm that product prices are now displayed in EURdiff --git a/docs/v5/user/how-to/multi-region-pricing.mdx b/docs/v5/user/how-to/multi-region-pricing.mdxindex addf23f5fe..c6c99518a1 100644--- a/docs/v5/user/how-to/multi-region-pricing.mdx+++ b/docs/v5/user/how-to/multi-region-pricing.mdx@@ -86,7 +86,7 @@ Repeat this entire process to create a second price list for Spain — name it `Once your markets and price lists are active, verify that the correct prices appear for each region.-1. Visit your storefront and look for the market switcher in the navigation. If you're using the Spree Next.js starter storefront, this appears in the navigation bar.+1. Visit your storefront and look for the market switcher in the navigation. If you're using the Spree Next.js Storefront, this appears in the navigation bar.2. Switch to **France / EUR** and note the price shown for a product you included in the France price list.3. Switch to **Spain / EUR** and confirm the price changes to reflect the Spain price list.4. Switch back to **Germany / EUR** and confirm the base EUR price is shown (since Germany has no regional price list).diff --git a/docs/videos/out.mp4 b/docs/videos/out.mp4new file mode 100644index 0000000000..e69de29bb2diff --git a/docs/videos/store-setup-web.mp4 b/docs/videos/store-setup-web.mp4new file mode 100644index 0000000000..0500311e60Binary files /dev/null and b/docs/videos/store-setup-web.mp4 differdiff --git a/docs/videos/store-setup.mp4 b/docs/videos/store-setup.mp4new file mode 100644index 0000000000..52a1b16ae3Binary files /dev/null and b/docs/videos/store-setup.mp4 differ