Product fields
Product fields standardize catalog metadata such as color, size, and material, whichever source it comes from. Once mapped, a field can improve recommendations, power Smart Search filters, and appear to shoppers.
Open Dashboard → Products → Product fields.
Field definitions
Definitions are shared across all of your websites. Four core fields are always available:
| Field | Type | Default use |
|---|---|---|
color | Text list | Search and recommendations |
size | Text list | Search and recommendations |
material | Text list | Search and recommendations |
pattern | Text list | Search and recommendations |
To add a custom field, complete the add form and select Add field:
- Field key — lowercase letters, digits, and underscores, starting with a letter; up to 64 characters.
- Field label — the display name, up to 100 characters.
- Value type — Text, Number, Boolean, or Text list.
- Applies to — Product and variant, Product, or Variant.
Custom fields start with every use turned off. Keys and types cannot be changed after creation. Edit the label inline, or use Archive field and Restore field instead of deleting.
Values are validated: text is 1–1,024 characters, lists hold up to 100 unique values, numbers are plain decimals, and booleans are true or false.
Map a source
Mappings and usage are configured per website and per catalog source.
- Choose the Website and the Catalog source: CSV or a connected Shopify or WooCommerce store for that website.
- For a store connection, run a product sync first. Upsurge discovers source fields from products it has already synced.
- Under Source mappings, choose the Product source field or Variant source field for each product field. Detected columns lists the keys that were found.
- Optionally add Value aliases, one per line, such as
Navy Blue = Navy, so spelling differences resolve to one value. - Select Preview conversions to check sample values without saving.
- Select Save mappings.
| Source | Source key format |
|---|---|
| Shopify | metafield.namespace.key for metafields, option.name for variant options |
| WooCommerce | attribute.name for attributes, meta.key for product meta |
| CSV | The exact column header |
Each product field takes one source per scope (product or variant). Aliases normalize spelling only; they do not convert units or sizes. BigCommerce is not currently offered as a mapping source.
Choose where a field is used
Each mapped field has four switches:
| Switch | Effect |
|---|---|
| Search | Include values in Smart Search matching. |
| Recommendations | Include values in product similarity and ranking. |
| Expose to shoppers | Allow values in public search and recommendation responses. |
| Allow facets | Make the field available as a Smart Search filter. Turning this on also turns on Search and Expose to shoppers. |
Facets appear only after you publish them in Smart Search. See Smart Search.
Saving mappings or usage queues a catalog refresh. Changes take effect as that refresh processes your products, which can take a while for large catalogs. If a mapped provider field has never been fetched, run a full sync to import it.
Local overrides
Values imported from a source are source values. Values you edit in the product editor are local overrides, and they stay in place when the product syncs again. A complete provider sync removes source values that no longer exist in the store, but keeps overrides. See Products.
How fields are used
- Recommendations: fields enabled for recommendations feed product similarity and ranking, with core fields first. Recommendation responses include only fields exposed to shoppers.
- Smart Search: fields enabled for search are matched. Published facets let shoppers filter by named values or numeric ranges. When several metadata filters are applied, they must all match the same available variant.
- Collections and merchandising: Smart Search rules can use a Metadata field condition.