Field Mappings
Field mappings translate canonical attribute codes from your catalogue into the specific field names expected by the destination platform (Magento, Shopify, WooCommerce).
Why field mappings are needed
Section titled “Why field mappings are needed”Each platform uses different field structures:
| Canonical attribute | Magento 2 | Shopify | WooCommerce |
|---|---|---|---|
delivery_days | custom_attributes.delivery_time | metafields.custom.delivery_days | meta_data.delivery_days |
weight | weight | weight | weight |
color | custom_attributes.color | options.Color | attributes.color |
Without field mappings, canonical attributes won’t appear on the destination platform unless they match a standard field name exactly.
Configuring field mappings
Section titled “Configuring field mappings”- Open an export profile
- Go to the Field Mappings tab
- Click Add mapping
- Select:
- Canonical attribute code: the attribute from your catalogue (e.g.
delivery_days) - Destination field: the path in the destination format (e.g.
custom_attributes.delivery_time) - Transform (optional): apply a transform before sending
- Canonical attribute code: the attribute from your catalogue (e.g.
Standard fields
Section titled “Standard fields”Standard product fields (name, description, price, stock, SKU, GTIN) are always exported automatically and don’t need field mappings.
Field mappings are only needed for custom/additional attributes beyond the standard set.
Transforms at export
Section titled “Transforms at export”The same transforms available for attribute mappings are also available at export time:
| Transform | Description |
|---|---|
trim | Remove whitespace |
regex_extract | Extract substring |
number_format | Format a number (decimal places, separator) |
prepend | Add prefix |
append | Add suffix |
This lets you format values for the destination’s requirements — for example, Magento might expect weight in grams while your catalogue stores it in kilograms.
Attribute overrides
Section titled “Attribute overrides”Attribute overrides set a fixed value for an attribute on exported products, optionally with conditions.
Example: Force brand_visible = false on all products from Supplier A:
- Condition:
supplier_id = Supplier A - Attribute:
brand_visible - Value:
false
Overrides are applied after pricing rules and before the export is sent to the destination.
Platform-specific notes
Section titled “Platform-specific notes”Magento 2
Section titled “Magento 2”Custom attributes use the custom_attributes.{code} path. The attribute must already exist as an EAV attribute in Magento with a matching code. CatalogRelay sends the value; Magento handles validation.
Shopify
Section titled “Shopify”Metafields use the metafields.{namespace}.{key} path. The namespace and key must match the metafield definition in Shopify. Standard product fields (title, body_html, vendor, product_type) are available without mappings.
WooCommerce
Section titled “WooCommerce”Custom attributes use the attributes.{name} path. Meta data uses meta_data.{key}. WooCommerce attribute names are case-sensitive.