Metafields
The Metafields settings allow you to customize the data structure of your store. While Soppiya provides standard fields (like Price, Description, and SKU), most businesses require specific data points unique to their industry—such as "Expiration Date" for food, "Fabric Material" for clothing, or "ISBN" for books.
Metafields effectively act as custom form fields, allowing you to store, retrieve, and display this specialized information on your storefront.
Location: Content → Metafields
What Are Metafields?
Metafields are custom data fields you define to extend the default information Soppiya stores for products, customers, orders, and other resources. They let you capture industry-specific details that aren't covered by standard fields.
- Custom Data Storage - Add fields like "Fabric Type", "Expiration Date", or "ISBN" to any resource
- Multiple Data Types - Support for text, numbers, dates, booleans, colors, and more
- Resource-Scoped - Each metafield belongs to one resource type (Product, Customer, Order, etc.)
- Public or Private - Control whether data is visible to customers or admin-only
Think of metafields as custom form fields. You define what data you want to collect, then fill in the values for each product, customer, or order individually.
Metafields Overview
The Metafields landing screen is the control center for all custom data definitions.
-
Resource List: When you open Content → Metafields, you'll see a list of supported resources. Metafields are resource‑scoped, meaning each metafield belongs to exactly one resource type and cannot be reused globally. Examples of resources include Product, Variant, Order, and Customer.
-
Definitions Table: Once you select a resource, the main area displays the current configuration.
- New Setup: If you have not created any fields yet, this list will be empty.
- Existing Fields: If fields exist, the table displays their Definition Name (internal label) and Content Type (data format). A search bar, filters, and sorting controls are available at the top to help manage larger sets of metafields.
Quick Start Guide
If you're setting up custom fields for the first time, follow these steps:
- Choose a resource — Decide which resource needs custom data (usually Product)
- Define the metafield — Create a definition with a name, type, and access setting
- Enter data — Navigate to specific items and fill in the custom field values
- Display on storefront — Connect the field to your theme via the Theme Editor (optional)
For detailed instructions, continue reading below.
Supported Resource Types
Before creating a field, you must select where that field should live. Click on one of the resources below to begin managing its fields.
| Resource | Best Used For... |
|---|---|
| Product | Technical specs, washing instructions, release dates. |
| Variant | Specific details for a size/color (e.g., distinct weight). |
| Collection | Promo text or banner images for specific categories. |
| Customer | Birthdays, loyalty tier, skin type preferences. |
| Order | Delivery instructions, gift wrap messages. |
| Article / Blog | Author profiles, "Reading Time" estimates. |
| Page | Custom SEO tags or team bios. |
| Location | Warehouse codes or manager contact info. |
| Market | Region-specific pricing notes or legal disclaimers. |
Creating a New Metafield Definition
To add a new data field to a resource:
- Select the Resource (e.g., Product).
- Click the button in the top right corner.
- Complete the configuration form detailed below.
Configuration Settings
These settings define how the system handles your data.
| Setting | Function & Rules |
|---|---|
| Name | The Display Label. This is what you see in the Admin panel. Keep it short and clear (e.g., Wash Instructions). |
| Namespace & Key | The System ID. Used by the API to find data. It auto-generates based on your Name, but you can manually edit it before saving. Limitation: Once saved, this ID is locked and cannot be changed. |
| Select Type | The Data Format. Defines what input is allowed. Examples: • Text (Words) • Integer (Whole numbers) • Date (Calendar picker) • Boolean (Yes/No switch) • Color (Color picker) |
| Value Type | The Quantity. • Single: Holds one value (e.g., "Cotton"). • Multiple: Holds a list of values (e.g., "Cotton", "Polyester"). |
| Public Access | The Visibility. • Enabled: Visible to the storefront/customers. • Disabled: Internal admin use only. |
Be careful when choosing between Text and Number. If you want to use the data for calculations (e.g., "Weight" or "Package Count"), you must use Number. You cannot perform math on a Text field, even if it only contains numbers.
Click button to create the definition.
Filtering and Viewing
As your store grows, you may manage dozens of fields. The Definitions Page includes filtering options to help you organize your view.
- Click and select Type.
- Choose one or more desired content types from the list (e.g., Date, Boolean, Reference).
- The list updates instantly.
Resetting: To see all fields again, click Clear all right side of the filter menu.
Managing Existing Metafield Definitions
Editing a Metafield Definition
Click on any Metafield Definition Name in the list to open its details.
- Editable: You can update the Name and Public Access settings at any time.
- Locked: To ensure data integrity, you cannot change the Namespace, Content Type, or Value Type once created.
Deleting a Metafield Definition
To remove a field that is no longer needed:
- Open the metafield details page.
- Click the button.
- Confirm the action.
Deleting a metafield definition is permanent. It will immediately erase all data associated with that field across all your products, pages, or customers. This action cannot be undone.
How to Input Data
Creating the definition (Steps 1-2) only builds the form. To use it, you must navigate to the specific item you want to update.
Example: Adding data to a Product
- Navigate to Products in your admin menu.
- Click on a specific product (e.g., Blue T-Shirt).
- Scroll to the bottom of the page to find the Metafields section.
- Enter the specific value into your custom field (e.g., select a date or type text).
- Click button.
Simply entering the data here does not automatically show it on your website. To display this information to customers, you must go to the Theme Editor and connect a text or image block to this dynamic source.
Real World Examples
To help you understand how metafields work in practice, here are common use cases.
Example 1: Product Fabric Material
Goal: Add a "Fabric Material" field to all products so customers can see what each item is made of.
Configuration:
| Setting | Value |
|---|---|
| Resource | Product |
| Name | Fabric Material |
| Type | Text |
| Value Type | Multiple |
| Public Access | Enabled |
Why this works:
- "Multiple" value type allows listing several materials (e.g., "Cotton", "Polyester")
- Public access ensures the data appears on the storefront
- Text type is appropriate since this is descriptive data, not numeric
Example 2: Customer Birthday for Loyalty Programs
Goal: Track customer birthdays to send automated birthday discount emails.
Configuration:
| Setting | Value |
|---|---|
| Resource | Customer |
| Name | Birthday |
| Type | Date |
| Value Type | Single |
| Public Access | Disabled |
Why this works:
- Date type provides a calendar picker for easy input
- Single value since each customer has one birthday
- Private access since birthday data should not be public
Example 3: Order Gift Message
Goal: Allow customers to add a personalized gift message to their order.
Configuration:
| Setting | Value |
|---|---|
| Resource | Order |
| Name | Gift Message |
| Type | Text |
| Value Type | Single |
| Public Access | Enabled |
Why this works:
- Text type allows free-form messages
- Public access enables the storefront to collect this data at checkout
- Single value since each order has one gift message
Troubleshooting
Common issues and how to fix them:
My metafield doesn't appear on the product page
Possible causes:
- The metafield data has been entered but not connected to the theme
- Public Access is disabled
Solution:
- Ensure Public Access is enabled for the metafield definition
- Go to the Theme Editor and connect a block to the metafield's dynamic source
- Verify you've actually entered data for the specific product — empty metafields won't display
I can't change the metafield type after creation
Possible causes:
- This is by design — Namespace, Content Type, and Value Type are locked after saving
Solution:
- Delete the existing metafield definition (this will erase all associated data)
- Create a new metafield with the correct type
- Re-enter the data for each item
Before deleting, export or note down the existing data so you can re-enter it for the new field.
I entered data but it's not showing on the storefront
Possible causes:
- The metafield is not connected to a theme block
- Public Access is disabled
Solution:
- Check the Public Access setting on the metafield definition — it must be enabled
- Go to Theme Editor → add or select a block → choose the metafield as the dynamic source
- Save and preview the page
I can't find my metafield in the product editor
Possible causes:
- The metafield was created under a different resource (e.g., Variant instead of Product)
- The metafield definition was deleted
Solution:
- Go to Content → Metafields and verify the field exists under the correct resource
- If it's under the wrong resource, you'll need to create a new definition under the correct one
- The metafield section appears at the bottom of the item's edit page — scroll down to find it
If you're still experiencing issues, contact Soppiya support with the metafield name, resource type, and a screenshot of your configuration.
Best Practices
Metafield Management Best Practices
Planning
- Plan before creating: Map out all the custom fields you need before creating them — you can't change the type after saving
- Choose types carefully: Use Number for anything you need to calculate; use Text for descriptive data only
- Use descriptive names: "Fabric Material" is better than "Material" — clarity helps when you have many fields
Organization
- Review by resource: Periodically check each resource type to remove unused definitions
- Use filters: When managing many fields, filter by type to quickly find what you need
- Document your fields: Keep a record of what metafields exist and their purpose, especially for developer handoff
Common Mistakes to Avoid
- ❌ Using Text type for numeric data — you won't be able to perform calculations
- ❌ Forgetting to set Public Access — data won't appear on the storefront without it
- ❌ Creating duplicate fields — search existing fields before adding new ones
- ❌ Deleting fields without backing up data — all associated data is permanently erased
Summary
Metafields extend Soppiya's default data structure by letting you create custom fields for any resource type. They are essential for storing industry-specific information that standard fields don't cover.
Key takeaways:
- Metafields are resource-scoped — each belongs to one resource type (Product, Customer, Order, etc.)
- Choose your data type carefully before saving — it cannot be changed later
- Enable Public Access if you want data visible on the storefront
- Creating a definition builds the form; you must enter data separately on each item
- Connect metafields to theme blocks via the Theme Editor to display them to customers
- Deletion is permanent and erases all associated data across every item
If you're just getting started, create one Product metafield (like "Fabric Material" or "Care Instructions"), enter data for a single product, and then connect it to your theme to see the full workflow.