> For the complete documentation index, see [llms.txt](https://help.mimeeq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.mimeeq.com/commerce-and-integrations/shopify/custom-field-mappings.md). # Custom Field Mappings Configure Ecommerce Custom Field Mappings in Mimeeq to send product metadata beyond SKU and price to Shopify or WooCommerce without custom development. ## Content 1. [Overview](#overview) 2. [Where to Find Field Mapping Settings](#where-to-find-field-mapping-settings) 3. [Setting Up Mappings](#setting-up-mappings) 4. [Platform-Specific Field Types](#platform-specific-field-types) 5. [Practical Examples](#practical-examples) 6. [Validation and Error Prevention](#validation-and-error-prevention) ## Overview **Ecommerce Custom Fields Mappings** allow you to pass additional product data — beyond the standard SKU and price — to your connected sales channel when a product or variant is created or added to cart. This lets you push configuration-specific metadata directly into Shopify products, Shopify variants, or WooCommerce product custom fields without any custom development. When a customer configures and adds a product to cart, Mimeeq normally sends the SKU code and price to your ecommerce platform. With Custom Field Mappings, you can also send: | Platfrom | Field Type | What It Targets | | --------------------- | ----------------- | ----------------------------------------------------------------- | | Shopify | Product Property | Standard Shopify product fields (vendor, barcode, tax code, etc.) | | Shopify | Product Metafield | Custom metadata stored on the Shopify product object | | Shopify | Variant Metafield | Custom metadata stored on a specific Shopify variant | | WordPress/WooCommerce | Product Metafield | Additional metadata attached to a WooCommerce product | These mappings are evaluated at the time of product/variant creation and the values are written directly to the ecommerce platform record. ## Where to Find Field Mapping Settings 1. Open any product in the Product Admin 2. Go to the **Pricing/Codes** tab 3. Scroll down to the **Add to Cart Configuration** section 4. Look for the **Ecommerce Custom Fields Mappings** collapsible panel ![Where to Find Field Mapping Settings](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FCzyatTKUwkPVx1kzJpxY%2Fmappings-1-new_w7l2ur.png?alt=media) ## Setting Up Mappings ### Step 1 — Select Your Method At the top of **Add to Cart Configuration**, choose a **Method**. The method controls how configured products are sent to your sales channel, and it directly determines how field mappings are structured. | Method | How it works | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Single Product | The configured product is added to cart as a single item, with all components combined into one product. This is the simplest approach. | | Custom Defined Logic | Gives you three independent options that can be used separately or together: creating single variants, custom products, or bundles. This method supports more complex product structures. | {% hint style="warning" %} For a full explanation of each method, see [Shopify Add to Cart Configuration Methods](/commerce-and-integrations/shopify/add-to-cart.md) {% endhint %} ### Step 2 — Select Your Integration Type Once you've selected a method, set the **Integration type**: | Integration Type | Connects to | | ---------------- | ----------------------- | | Shopify | Mimeeq Shopify App | | WordPress | Mimeeq WordPress Plugin | The available mapping types update automatically based on your selection. ### Step 3 — Configure Your Field Mappings How you configure field mappings depends on the method selected in Step 2. #### If you selected Single Product A single flat mappings table is available. Click **Add row** to add individual field mappings directly. Each row has three fields: | Column | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Type | The type of field on the ecommerce platform — see platform-specific options below | | Field / Key | The field name or identifier — format depends on the Type selected | | Value | The value to write to that field — can be a static value or a formula | | Skip on failure | Controls what happens if this mapping fails. If unchecked (default), a failed mapping blocks the add-to-cart action. If checked, the field is skipped and the product is still added to cart | All mappings defined here are automatically applied to every product created via this configurator. {% hint style="warning" %} When to use Skip on failure: Enable it for non-critical fields — such as supplementary metafields, internal tags, or informational properties — where a missing value is acceptable and you don't want a formula issue to prevent the customer from completing their purchase. -Leave it disabled for required fields— such as `countryCodeOfOrigin` or tax codes — where a missing or incorrect value could cause downstream fulfilment, compliance, or taxation problems. If Skip on failure is unchecked and a mapping fails, the customer will be unable to add the product to cart. Make sure formulas and static values are correct before publishing, or enable Skip on failure for fields that are optional. {% endhint %} ![Configuring Field Mappings for Single Product](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FdH33Wwy216qaKrkNsLKR%2Fmappings-2-new_1n72cuq.png?alt=media) #### If you selected Custom Defined Logic You can create one or more **mapping groups**, each containing its own set of field mappings. Groups can then be assigned to specific custom products and admin bundles. Click **Add mapping group** to create a group. Each group: * Has an optional **Mapping Group Name** for internal reference (not shown to customers) * Contains one or more individual field mapping rows * Can be added or removed as needed Each row within a group has the same three fields as above: **Type**, **Field / Key**, **Value and Skip on failure**. {% hint style="warning" %} For most products, one mapping group is sufficient. Multiple groups are useful when you need to organise mappings by function (e.g. "Tax Fields", "Logistics Fields", "Custom Attributes") or when using the Custom Defined Method where admin bundles or custom products need different mapping sets. {% endhint %} ![Configuring Field Mappings for Custom Defined Logic](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FqgXMqQI6F1bbaMnfoVX5%2Fmappings-3-new_5gl1bx.png?alt=media) ## Platform-Specific Field Types ### Shopify — Product Property Maps to standard built-in Shopify product fields. Select from the predefined list: | Field Key | What It Sets in Shopify | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `vendor` | Product vendor / manufacturer | | `productType` | Shopify product type | | `barcode` | Product or variant barcode (EAN, UPC, ISBN) | | `taxable` | Whether the product is taxable (`true` / `false`) | | `taxCode` | Tax code for the product | | `tracked` | Whether inventory is tracked (`true` / `false`) | | `requiresShipping` | Whether shipping is required (`true` / `false`) | | `countryCodeOfOrigin` | ISO 3166-1 alpha-2 country code (e.g. `GB`, `DE`, `US`) | | `harmonizedSystemCode` | HS tariff code for international customs | | `themeTemplate` | Default theme product page template assigned to newly created products. Overrides the Product Template set in the [Configurator Settings.](/commerce-and-integrations/shopify/admin-settings.md#dynamic-fields-settings) | ### Shopify — Product Metafield & Variant Metafield Maps to custom metadata stored on the Shopify product or variant object. **Key format:** `namespace.key` ``` custom.lead_time custom.sku_internal myapp.product_category ``` **Validation rules:** * Must contain exactly one dot (`.`) separator * Namespace: 3–255 characters * Key: 2–64 characters **Finding Your Metafield Key in Shopify** If you're not sure what key to use, you can look it up directly in your Shopify admin: 1. Navigate to **Settings → Custom data** in your Shopify admin 2. Select **Products** (or **Variants**, depending on your metafield type) under the Metafields section 3. Locate the metafield definition you want to use 4. Copy the key shown in the definition — it will already be in `namespace.key` format (e.g. `custom.lead_time`) 5. Paste that key into the **Field / Key** column in the Ecommerce Custom Fields Mappings panel {% hint style="warning" %} ⚠️ Important: If a metafield key is incorrect or the value does not meet Shopify's validation requirements, Shopify will return an error. Whether this blocks the add-to-cart action depends on the Skip on failure setting for that row. If unchecked (default), a failed mapping blocks the add-to-cart action. If checked, the field is skipped and the product is still added to cart. {% endhint %} ![Metafield Key in Shopify](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FloOch3JZuQi8g4wdwq3T%2Fmappings-4_dyqhgy.png?alt=media) ### WordPress (WooCommerce) — Product Metafield Maps to WooCommerce product `_meta` fields. **Key format:** `snake_case` ``` custom_sku lead_time_days product_origin ``` **Validation rules:** * 1–255 characters * Lowercase alphanumeric with underscores only * Must match the pattern `lowercase_with_underscores` ### The Value Field **Static Values** Plain text or numbers written exactly as entered: ``` United Kingdom true GB 9401.61 ``` **Dynamic Formulas** Start the value with `=` to reference configuration data. Formulas can pull from: * Option selections made by the customer during configuration * Item Master data fields * Mathematical calculations **Examples:** ``` ={fabric#code} ={frame_material#name} ={width_cm#value} ``` This means the value written to Shopify or WooCommerce can reflect exactly what the customer configured — for example, writing the selected material code as a searchable product metafield. ## Practical Examples #### Example 1 — Write a Material Code to a Shopify Variant Metafield Store the selected fabric code in a Shopify variant metafield for use in order workflows. | Type | Field / Key | Value | Skip on failure | | ----------------- | -------------------- | ---------------- | --------------- | | Variant Metafield | `custom.fabric_code` | `={fabric#code}` | ✅ | **Result:** When a customer selects fabric `LINEN_NATURAL` and adds to cart, the Shopify variant record will include `custom.fabric_code = LINEN_NATURAL`. #### Example 2 — Set Customs Data for Export Products Apply HS code, country of origin, and tax code to every product created via this configurator. | Type | Field / Key | Value | Skip on failure | | ---------------- | ---------------------- | ---------- | --------------- | | Product Property | `harmonizedSystemCode` | `9401.61` | ✅ | | Product Property | `countryCodeOfOrigin` | `GB` | ❌ | | Product Property | `taxCode` | `STANDARD` | ✅ | #### Example 3 — Pass Lead Time to WooCommerce Write the lead time for the selected material to a WooCommerce custom field. | Type | Field / Key | Value | Skip on failure | | -------------------- | ---------------- | ---------------------------- | --------------- | | Product Custom Field | `lead_time_days` | `={material#lead_time_days}` | ✅ | Each material option carries its own lead time value (e.g. `14` for standard, `28` for bespoke), which is passed through dynamically. #### Example 4 — Tag Bespoke Variants with a Custom Metafield Flag made-to-measure products using a combination of a static taxable value and a dynamic bespoke identifier. | Type | Field / Key | Value | Skip on failure | | ----------------- | ------------------- | ---------------------- | --------------- | | Product Property | `taxable` | `true` | ✅ | | Variant Metafield | `custom.is_bespoke` | `={product_type#code}` | ✅ | ## Validation and Error Prevention | Rule | Detail | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Duplicate keys** | Duplicate keys within the same mapping group are not allowed. An *(already used)* indicator appears and saving is blocked. | | **Invalid Shopify metafield format** | Keys must follow `namespace.key` format. An error message appears if the format is incorrect. | | **Invalid WordPress key format** | Keys must be `snake_case`. An error appears for any invalid characters. | | **Shopify validation errors** | If Shopify rejects a value (e.g. incorrect type or format), the product will not be created. If Skip on failure is enabled for that row, the field is skipped rather than blocking the cart. These errors come from Shopify directly and must be corrected by the user. | | **Failed mapping with Skip on failure unchecked** | If a mapping fails and Skip on failure is disabled, the add-to-cart action is blocked. Check the field value or formula, or enable Skip on failure if the field is non-critical. | ## Related Articles 1. [Shopify Add to Cart Configuration Methods](/commerce-and-integrations/shopify/add-to-cart.md) 2. [Shopify Latest Version Updates: Your Guide to New Features and Enhancements](/commerce-and-integrations/shopify/changelog.md) 3. [Custom Ecommerce Integration](/commerce-and-integrations/custom-commerce/integration-guide.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.mimeeq.com/commerce-and-integrations/shopify/custom-field-mappings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.