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
Added metafields user documentation (#13278)
jaburghesb884fedc9dd6
diff --git a/docs/docs.json b/docs/docs.jsonindex e866521d07..a986f2eed8 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -1007,6 +1007,7 @@"user/settings/checkout","user/settings/domains","user/settings/locations",+ "user/settings/metafields","user/settings/payments","user/settings/zones","user/settings/shipping-methods",diff --git a/docs/images/user/products/properties/1-product-properties.png b/docs/images/user/products/properties/1-product-properties.pngnew file mode 100644index 0000000000..d3e36176c4Binary files /dev/null and b/docs/images/user/products/properties/1-product-properties.png differdiff --git a/docs/images/user/products/properties/2-add-property.png b/docs/images/user/products/properties/2-add-property.pngnew file mode 100644index 0000000000..dbc3efb440Binary files /dev/null and b/docs/images/user/products/properties/2-add-property.png differdiff --git a/docs/images/user/products/properties/3-pdp-display.png b/docs/images/user/products/properties/3-pdp-display.pngnew file mode 100644index 0000000000..01947fec0fBinary files /dev/null and b/docs/images/user/products/properties/3-pdp-display.png differdiff --git a/docs/images/user/products/properties/4-properties-ordering.png b/docs/images/user/products/properties/4-properties-ordering.pngnew file mode 100644index 0000000000..7d63d7437dBinary files /dev/null and b/docs/images/user/products/properties/4-properties-ordering.png differdiff --git a/docs/images/user/products/properties/5-edit-properties.png b/docs/images/user/products/properties/5-edit-properties.pngnew file mode 100644index 0000000000..e7ec2a9445Binary files /dev/null and b/docs/images/user/products/properties/5-edit-properties.png differdiff --git a/docs/images/user/products/properties/6-delete-properties.png b/docs/images/user/products/properties/6-delete-properties.pngnew file mode 100644index 0000000000..2439b22b68Binary files /dev/null and b/docs/images/user/products/properties/6-delete-properties.png differdiff --git a/docs/images/user/settings/metafields/1-settings-metafields.png b/docs/images/user/settings/metafields/1-settings-metafields.pngnew file mode 100644index 0000000000..48664b961cBinary files /dev/null and b/docs/images/user/settings/metafields/1-settings-metafields.png differdiff --git a/docs/images/user/settings/metafields/2-create-a-metafield.png b/docs/images/user/settings/metafields/2-create-a-metafield.pngnew file mode 100644index 0000000000..0ec70b8fefBinary files /dev/null and b/docs/images/user/settings/metafields/2-create-a-metafield.png differdiff --git a/docs/images/user/settings/metafields/3-metafield-resource.png b/docs/images/user/settings/metafields/3-metafield-resource.pngnew file mode 100644index 0000000000..672b3f6ffcBinary files /dev/null and b/docs/images/user/settings/metafields/3-metafield-resource.png differdiff --git a/docs/images/user/settings/metafields/4-metafield-type.png b/docs/images/user/settings/metafields/4-metafield-type.pngnew file mode 100644index 0000000000..54a6c55768Binary files /dev/null and b/docs/images/user/settings/metafields/4-metafield-type.png differdiff --git a/docs/images/user/settings/metafields/5-add-metafield-value.png b/docs/images/user/settings/metafields/5-add-metafield-value.pngnew file mode 100644index 0000000000..12c8ac448cBinary files /dev/null and b/docs/images/user/settings/metafields/5-add-metafield-value.png differdiff --git a/docs/images/user/settings/metafields/6-select-metafields.png b/docs/images/user/settings/metafields/6-select-metafields.pngnew file mode 100644index 0000000000..480c935684Binary files /dev/null and b/docs/images/user/settings/metafields/6-select-metafields.png differdiff --git a/docs/images/user/settings/metafields/7-enter-metafield-values.png b/docs/images/user/settings/metafields/7-enter-metafield-values.pngnew file mode 100644index 0000000000..6a7df17134Binary files /dev/null and b/docs/images/user/settings/metafields/7-enter-metafield-values.png differdiff --git a/docs/user/manage-products/product-properties.mdx b/docs/user/manage-products/product-properties.mdxindex 605c6a0eef..67cd3ab897 100644--- a/docs/user/manage-products/product-properties.mdx+++ b/docs/user/manage-products/product-properties.mdx@@ -3,105 +3,79 @@ title: "Product Properties"description: "How to manage product properties in the Spree open-source eCommerce dashboard"----Product properties provide detailed specifications, such as dimensions, materials, care instructions, allergen warnings, etc., that help customers make informed purchase decisions.+<Warning>+**Starting with Spree 5.2**, Metafields are the **recommended default** for storing custom product attributes, replacing the legacy [Product Properties](/developer/core-concepts/products#product-properties) system. For new projects, use [Metafields](/user/settings/metafields) instead of Properties.-They streamline inventory management by standardizing key product details across listings. Additionally, product properties enhance product listings by highlighting unique features that differentiate items from competitors.--To manage product Properties, navigate to the Properties tab of the admin dashboard found under Products.--<img alt="Product Properties" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626565/docs/Manage%20Products/Product%20Properties/2.6.1_Properties_-_Navigate_To_Tab_cnxdhz.png" />--This page lists all of the product properties added to your store, with columns indicating the kind of property, how many products have the property, and the visibilility of the property.--## Add a New Property--To add a new property, click ‘+ New Property’ in the top right corner.--This will open the property creation page.--<img alt="Add A New Property" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626565/docs/Manage%20Products/Product%20Properties/2.6.2_Properties_-_Add_A_New_Property_gnhjyk.png" />--### Presentation--In the top two fields, you can set the name of the property. Presentation is how the property will be displayed on the storefront.--If an Internal Name is not set, the Presentation name will be used.+Product Properties are still supported for backward compatibility (until Spree 6.0) but require enabling via `config.product_properties_enabled = true`. See the [upgrade guide](/developer/upgrades/5.1-to-5.2#3-migrate-to-metafields-or-keep-using-properties) for migration details.+</Warning>-<img alt="Presentation" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626564/docs/Manage%20Products/Product%20Properties/2.6.3_Properties_-_Presentation_jgnmsz.png" />+Product properties provide detailed specifications, such as dimensions, materials, care instructions, allergen warnings, etc., that help customers make informed purchase decisions.-### Kind--Kind indicates the type of values the property field should store, e.g.:--* Short text--* Long text--* Number--* Rick Text--<img alt="Kind" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626565/docs/Manage%20Products/Product%20Properties/2.6.4_Properties_-_Kind_xkahvm.png" />+They streamline inventory management by standardizing key product details across listings. Additionally, product properties enhance product listings by highlighting unique features that differentiate items from competitors.-### Display+To manage product Properties, navigate to the Properties tab of the admin dashboard found under Products.-Controls where the Property will be displayed, i.e., for who is the information relevant:+-* On both admin panel & storefront, i.e., useful for admins and customers+This page lists all of the product properties added to your store, with columns indicating the kind of property, how many products have the property, and the visibility of the property.-* Only on storefront, i.e., only useful for customers+### Add a New Property-* Only on admin panel, i.e., only useful for admins+To add a new property, click **New Property** in the top right corner to open the product property creation page.-<img alt="Display On" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626565/docs/Manage%20Products/Product%20Properties/2.6.5_Properties_-_Display_On_em37wp.png" />+-If the product is visible on the storefront, it will be presented below the product description on PDPs if and only if the product has a non-empty value for that property field:+When creating a new property field, you’ll see the following form inputs:-<img alt="Storefront" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626567/docs/Manage%20Products/Product%20Properties/2.6.6_Properties_-_Storefront_mh6yho.png" />+- **Presentation** - the display name of the property shown on the storefront (if visible).+- **Internal Name** - a unique identifier used in the backend. If left blank, it will default to the Presentation name.+- **Kind** - defines the type of value this property stores:+ - **Short Text** - e.g., “Cotton”+ - **Long Text** - e.g., “Made from organically grown cotton harvested in Japan”+ - **Number** - e.g., “10”+ - **Rich Text** - supports formatted content (e.g. bold, lists)+- **Display** - Controls where the property is shown:+ - **Both admin panel & storefront** - useful for customers and admins alike+ - **Only on storefront** - e.g., material, country of origin+ - **Only on admin panel** - e.g., internal notes, restocking schedule-### Click Create+Once you’ve completed all of the fields, click the **Create** to save your new product property.-Once you’ve completed all of the fields, click the blue ‘Create’ button at the bottom of the page, and the property will be created.+If a product is visible on the storefront, the property will appear (if it has a non-empty value) below the product description on PDPs as shown below:-<img alt="Click Create" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626566/docs/Manage%20Products/Product%20Properties/2.6.7_Properties_-_Click_Create_ppz4zn.png" />+-## Properties Management+### Properties Management-Navigating back to the Properties page, you’ll see that your newly created option is now listed among your other Properties.+From the Properties tab, there are a number of ways in which you can edit product properties:-<img alt="Management" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626565/docs/Manage%20Products/Product%20Properties/2.6.8_Properties_-_Management_dktdhj.png" />+#### Properties Ordering-### Properties Ordering+If you’d like to change the order in which properties are displayed on the storefront, e.g., on product detail pages, you can drag and drop them into position by clicking on the 6 dots on the left hand side.-<img alt="Ordering" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626573/docs/Manage%20Products/Product%20Properties/2.6.9_Properties_-_Ordering_cb9tpf.png" />--### Editing Properties+#### Editing Properties-To edit a property, navigate to the Properties tab, and click ‘Edit’ on the property you’d like to edit.+To edit a property, navigate to the Properties tab, and click **Edit** on the property you’d like to edit.-<img alt="Edit A Property" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626573/docs/Manage%20Products/Product%20Properties/2.6.10_Properties_-_Edit_A_Property_gharxz.png" />+Feel free to change the Presentation Name, Internal Name, Kind, and Display On fields.-<img alt="Make Changes and Update" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626573/docs/Manage%20Products/Product%20Properties/2.6.11_Properties_-_Make_Changes_and_Update_dddcou.png" />--Once you’re finished, make sure to click the blue ‘Update’ button at the bottom of the page.+Once you’re finished, make sure to click **Update** to save your changes.### Delete Properties-To delete a property, navigate to the Properties tab, and click ‘Edit’ on the property you’d like to delete.--On the property editor page, locate the red ‘Delete’ button at the bottom of the page and the property will be deleted.+To delete a property, click on the **three-dot menu** in the top right corner and select **Delete** from the dropdown menu, or simply click **Delete** in the bottom right corner.-<img alt="Delete A Property" classname="block dark:hidden" src="https://vendo-production-res.cloudinary.com/image/upload/w_1920/q_auto/v1734626574/docs/Manage%20Products/Product%20Properties/2.6.12_Properties_-_Delete_A_Property_vfengh.png" />+-## Import Properties+### Import Properties-Properties can be automatically imported if you add the appropriate values to the properties columns in a product import file.+Properties can be automatically imported if you add the appropriate values to the properties columns in a product import file.-To learn more about imports, please refer to the [Product Imports](https://spreecommerce.org/docs/user/manage-products/import-products) support article.+To learn more about product imports, please refer to our [<u>CSV Importer</u>](https://spreecommerce.org/docs/user/manage-products/import-products) support article.## Real-Life Examples: Product Options vs Product Properties@@ -119,4 +93,4 @@ Let’s dive deep into how these tools can revolutionize your product presentati5. [Bringing It All Together in Spree 5](https://spreecommerce.org/product-properties-and-product-options-a-strategic-guide-to-improving-conversions-and-seo/#Spree-5)-6. [Next Steps](https://spreecommerce.org/product-properties-and-product-options-a-strategic-guide-to-improving-conversions-and-seo/#Next-Steps)\ No newline at end of file+6. [Next Steps](https://spreecommerce.org/product-properties-and-product-options-a-strategic-guide-to-improving-conversions-and-seo/#Next-Steps)diff --git a/docs/user/settings/metafields.mdx b/docs/user/settings/metafields.mdxnew file mode 100644index 0000000000..4e013f35a0--- /dev/null+++ b/docs/user/settings/metafields.mdx@@ -0,0 +1,116 @@+---+title: "Metafields"+description: "Learn how to define and use metafields in Spree Commerce"+---++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.++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.++## Creating a New Metafield++To create a metafield definition go to **Settings → Metafield Definitions**++++Here you’ll see a list of all existing metafield definitions in your store.++To add a new one, click **New Metafield 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+ - 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)+- **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:++- **Address** - e.g., delivery instructions+- **Asset** - e.g., alt text or copyright+- **Credit Card** - e.g., vault token+- **Custom Domain** - e.g., domain verification token+- **Customer Return** - e.g., return reason detail+- **Gift Card** - e.g., personal message+- **Image** - e.g., display priority or alt tag+- **Line Item** - e.g., engraving or personalization notes+- **Newsletter Subscriber** - e.g., subscription source+- **Option Type**+- **Option Value** - e.g., color hex code+- **Order** - e.g., internal comment, PO number+- **Payment** - e.g., external transaction reference+- **Payment Method** - e.g., risk profile or processor ID+- **Payment Source** - e.g., metadata from payment gateway+- **Post** - e.g., featured tag+- **Post Category** - e.g., CTA label+- **Product** - e.g., material, sustainability rating, care instructions+- **Promotion** - e.g., campaign name+- **Refund** - e.g., refund reason detail+- **Shipment** - e.g., fragile/handling notes+- **Shipping Method** - e.g., carrier code+- **Stock Item** - e.g., e.g., warehouse bin location+- **Stock Transfer** - e.g., batch ID or receiving note+- **Store** - e.g., store tagline or branding metadata+- **Store Credit** - e.g., usage restrictions+- **Tax Rate** - e.g., compliance category+- **Taxon** - e.g., display badge (“New”, “Sustainable”)+- **Taxonomy** - e.g., navigation group metadata+- **Variant** - e.g., spec sheet URL, sizing details+- **User** - e.g., loyalty tier+- **Vendor** - e.g., vendor profile details++### 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.++- **Short Text** - for single-line strings, e.g., "Cotton" or "Blue"+- **Long Text** - multi-line content, e.g., care instructions+- **Rich Text** - text with formatting options, e.g., marketing blocks+- **Number** - any numeric value, e.g., 4.5 (rating), 12 (inches)+- **Boolean** - true/false flags, e.g., “Is this product fragile?” = true+- **JSON** - for structured data or multiple related attributes++## Adding Metafield Values++Once your metafield definition has been created, you can enter values in a few different ways:++### Individually in the Admin Dashboard++First, 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.++++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.++### In Bulk (Products Only)++Product metafields 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)+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++This is ideal for large-scale changes across multiple products, especially when onboarding a large catalog.