> 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 Custom Field Mappings

Send product metadata beyond SKU and price to Shopify or WooCommerce without custom development. Learn to set up field mappings, formulas and validation.

**Ecommerce Custom Fields Mappings** let you 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. 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:

<table><thead><tr><th width="75.171875">#</th><th>Platform</th><th>Field type</th><th>What it targets</th></tr></thead><tbody><tr><td>1</td><td>Shopify</td><td><strong>Product Property</strong></td><td>Standard Shopify product fields (vendor, barcode, tax code, etc.)</td></tr><tr><td>2</td><td>Shopify</td><td><strong>Product Metafield</strong></td><td>Custom metadata stored on the Shopify product object</td></tr><tr><td>3</td><td>Shopify</td><td><strong>Variant Metafield</strong></td><td>Custom metadata stored on a specific Shopify variant</td></tr><tr><td>4</td><td>WordPress/WooCommerce</td><td><strong>Product Metafield</strong></td><td>Additional metadata attached to a WooCommerce product</td></tr></tbody></table>

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. Open the **Ecommerce Custom Fields Mappings** collapsible panel.

![Ecommerce Custom Fields Mappings panel in the Add to Cart Configuration section of the Pricing/Codes tab](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)

***

## Set up mappings

{% stepper %}
{% step %}

### 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.

<table><thead><tr><th width="52.0390625">#</th><th width="193.1328125">Method</th><th>How it works</th></tr></thead><tbody><tr><td>1</td><td><strong>Single Product</strong></td><td>The configured product is added to cart as a single item, with all components combined into one product. This is the simplest approach.</td></tr><tr><td>2</td><td><strong>Custom Defined Logic</strong></td><td>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.</td></tr></tbody></table>

For a full explanation of each method, see [Shopify Add to Cart Methods](/commerce-and-integrations/shopify/add-to-cart.md).
{% endstep %}

{% step %}

### Select your integration type

Once you've selected a method, set the **Integration type**:

<table><thead><tr><th width="218.28515625">Integration type</th><th>Connects to</th></tr></thead><tbody><tr><td><strong>Shopify</strong></td><td>Mimeeq Shopify App</td></tr><tr><td><strong>WordPress</strong></td><td>Mimeeq WordPress Plugin</td></tr></tbody></table>

The available mapping types update automatically based on your selection.
{% endstep %}

{% step %}

### Configure your field mappings

How you configure field mappings depends on the method you selected in the first step. See the options for each method below.
{% endstep %}
{% endstepper %}

### Field mappings by method

{% tabs %}
{% tab title="Single Product" %}
A single flat mappings table is available. Click **Add row** to add individual field mappings directly.

Each row has four fields:

<table><thead><tr><th width="171.80859375">Column</th><th>Description</th></tr></thead><tbody><tr><td><strong>Type</strong></td><td>The type of field on the ecommerce platform (see the platform-specific options below)</td></tr><tr><td><strong>Field / Key</strong></td><td>The field name or identifier; the format depends on the <strong>Type</strong> selected</td></tr><tr><td><strong>Value</strong></td><td>The value to write to that field; can be a static value or a formula</td></tr><tr><td><strong>Skip on failure</strong></td><td>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</td></tr></tbody></table>

All mappings defined here are automatically applied to every product created via this configurator.

![Single Product mappings table with Type, Field / Key, Value and Skip on failure columns](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)
{% endtab %}

{% tab title="Custom Defined Logic" %}
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 four fields as above: **Type**, **Field / Key**, **Value** and **Skip on failure**.

![Custom Defined Logic mapping groups, each with its own field mapping rows](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)
{% endtab %}
{% endtabs %}

{% hint style="success" %}
**Tip:** 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 %}

{% 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 %}

***

## Platform-specific field types

### Shopify: Product Property

Maps to standard built-in Shopify product fields. Select from the predefined list:

<table><thead><tr><th width="218.5546875">Field key</th><th>What it sets in Shopify</th></tr></thead><tbody><tr><td><code>vendor</code></td><td>Product vendor / manufacturer</td></tr><tr><td><code>productType</code></td><td>Shopify product type</td></tr><tr><td><code>barcode</code></td><td>Product or variant barcode (EAN, UPC, ISBN)</td></tr><tr><td><code>taxable</code></td><td>Whether the product is taxable (<code>true</code> / <code>false</code>)</td></tr><tr><td><code>taxCode</code></td><td>Tax code for the product</td></tr><tr><td><code>tracked</code></td><td>Whether inventory is tracked (<code>true</code> / <code>false</code>)</td></tr><tr><td><code>requiresShipping</code></td><td>Whether shipping is required (<code>true</code> / <code>false</code>)</td></tr><tr><td><code>countryCodeOfOrigin</code></td><td>ISO 3166-1 alpha-2 country code (e.g. <code>GB</code>, <code>DE</code>, <code>US</code>)</td></tr><tr><td><code>harmonizedSystemCode</code></td><td>HS tariff code for international customs</td></tr><tr><td><code>themeTemplate</code></td><td>Default theme product page template assigned to newly created products. Overrides the <strong>Product Template</strong> set in the <a href="/commerce-and-integrations/shopify/admin-settings.md#dynamic-fields-settings">Configurator Settings</a></td></tr></tbody></table>

### Shopify: Product Metafield and 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

#### Find your metafield key in Shopify

If you're not sure which key to use, look it up 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 is already 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 returns 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 definition in Shopify Settings → Custom data showing the namespace.key format](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}
```

The value written to Shopify or WooCommerce can reflect exactly what the customer configured. For example, you can write the selected material code as a searchable product metafield.

***

## Practical examples

### 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 includes `custom.fabric_code = LINEN_NATURAL`.

### Set customs data for export products

Apply the 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` | ✅               |

### 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.

### 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

<table><thead><tr><th width="259.08203125">Rule</th><th>Detail</th></tr></thead><tbody><tr><td><strong>Duplicate keys</strong></td><td>Duplicate keys within the same mapping group are not allowed. An <em>(already used)</em> indicator appears and saving is blocked.</td></tr><tr><td><strong>Invalid Shopify metafield format</strong></td><td>Keys must follow the <code>namespace.key</code> format. An error message appears if the format is incorrect.</td></tr><tr><td><strong>Invalid WordPress key format</strong></td><td>Keys must be <code>snake_case</code>. An error appears for any invalid characters.</td></tr><tr><td><strong>Shopify validation errors</strong></td><td>If Shopify rejects a value (e.g. incorrect type or format), the product will not be created. If <strong>Skip on failure</strong> 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.</td></tr><tr><td><strong>Failed mapping with Skip on failure unchecked</strong></td><td>If a mapping fails and <strong>Skip on failure</strong> is disabled, the add-to-cart action is blocked. Check the field value or formula, or enable <strong>Skip on failure</strong> if the field is non-critical.</td></tr></tbody></table>

***

## Related articles

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Shopify Add to Cart Methods</strong></td><td>Choose how configured products and bundles reach the cart.</td><td><a href="/commerce-and-integrations/shopify/add-to-cart.md">Shopify Add to Cart Methods</a></td></tr><tr><td><strong>Integration Guide</strong></td><td>Integrate Mimeeq with any commerce store using our APIs.</td><td><a href="/commerce-and-integrations/custom-commerce/integration-guide.md">Integration Guide</a></td></tr><tr><td><strong>Shopify Admin Settings</strong></td><td>Connect your API key, products and cart settings.</td><td><a href="/commerce-and-integrations/shopify/admin-settings.md">Shopify Admin Settings</a></td></tr><tr><td><strong>Shopify Error Recovery Center</strong></td><td>Track errors and follow up with affected customers.</td><td><a href="/commerce-and-integrations/shopify/error-recovery.md">Shopify Error Recovery Center</a></td></tr></tbody></table>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.mimeeq.com/commerce-and-integrations/shopify/custom-field-mappings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.