# Metafields and data mapping

URL: https://docs.sparklayer.io/help/platforms/shopify/metafields
Applies to: Shopify

Let SparkLayer add its Shopify metafields, fill them in for many products at once in the bulk editor, map order data and import order history.

> **Quick summary**
>
> - SparkLayer reads Shopify metafields for B2B settings such as pack sizes, RRP and credit limits. The [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) reference lists every one.
> - Metafields are optional. You don't need any to install SparkLayer or start taking B2B orders. Add them only when you want a feature that uses one.
> - SparkLayer creates the fields for you at **Integrations > Platform > Metafields** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform > Metafields** in the Shopify app. Fill them in on one product or customer, or on hundreds at once in Shopify's bulk editor.
> - Where a value has a set format (JSON), the feature's page has a **Build the value** form that writes it for you.

## How it works

[Metafields](https://help.shopify.com/en/manual/custom-data/metafields) are extra fields you can add to products, customers and orders in Shopify, to store information Shopify doesn't capture by default. Each SparkLayer metafield turns on or configures a specific B2B feature:

| Type | What SparkLayer uses them for |
| --- | --- |
| **Product metafields** | Settings for the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md) |
| **Customer metafields** | Customer settings, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |
| **Order metafields** | Order details, such as [invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) |

Setting one up takes two steps: SparkLayer [adds the field](#add-metafields-automatically) once, then you [fill it in](#fill-in-metafields). Keep two things in mind:

- **Product metafields go on variants.** Fill them in on each product variant, never the product, even if the product has only one variant.
- **Some values are JSON.** A few settings, such as credit limits, are written in a set format (JSON), for example `{"net_terms":"30_days"}`. Their pages have a **Build the value** form that writes it for you to copy.

## Add metafields automatically

SparkLayer can create its metafields in Shopify for you. This is the easiest way to add them, and needs no technical knowledge.

1. Go to **Integrations > Platform** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/integrations/platform)), or **SparkLayer Wholesale > Integrations > Platform** in the Shopify app.
2. In the **Metafields** card (**SparkLayer metafields**), click **Configure**.
3. The **Metafield Configuration** window lists the metafields you can add for **Product** and **Customer** data, such as **Pack Size**, **Reserved DTC Stock Quantity**, **Restock Date** and **Stock Location Settings**. Click **Enable** beside each one you want. The metafield shows a green tick.

SparkLayer only reads a metafield once it's enabled here. If you've created a definition yourself in Shopify, enable it here too.

Each metafield you enable is added to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) in Shopify and pinned, so it appears at the top of the metafields on each product or customer. Its name starts with `B2B -`, for example `B2B - Pack Size`.

To change or remove these metafields, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) in Shopify.

## Fill in metafields

Once a field exists, fill it in whichever way suits how many products or customers you're changing.

### One product or customer

Open the product variant, customer or order in Shopify and enter the value in its **Metafields** card. Click **Show all** if you can't see the field.

For example, you can set [payment terms](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) on a customer, such as `{"net_terms":"30_days"}`, or a [customer-specific discount](https://docs.sparklayer.io/help/pricing/customer-pricing.md) (**Customer % Discount**).

### Many at once

Shopify's bulk editor shows a metafield as a column, so you can fill in hundreds of products or customers in one table, without opening each one:

1. In your Shopify admin, go to **Products** ([open in the Shopify admin](https://admin.shopify.com/products)) or **Customers** ([open in the Shopify admin](https://admin.shopify.com/customers)) and tick the ones to change. To change them all, tick the box at the top of the list.
2. Click **Edit products** or **Edit customers**.
3. Click **Columns** and, under **Metafields**, tick the SparkLayer fields you want, such as **B2B - Pack Size**.
4. Type each value. For products, each variant has its own row.
5. Click **Save**. If a value is in the wrong format, Shopify highlights it: fix it and click **Save** again.

See Shopify's guide to [editing metafields in bulk](https://help.shopify.com/en/manual/custom-data/metafields/bulk-edit-metafields).

### From a spreadsheet

For thousands of rows, or values you already keep in a spreadsheet, use an import app. We recommend [Matrixify](https://apps.shopify.com/excel-export-import), which reads metafield columns from a spreadsheet and imports them in bulk.

## Add metafields by hand

You only need this for a metafield SparkLayer doesn't create for you. Add a metafield definition in Shopify, then [fill in its value](#fill-in-metafields). Shopify's [metafields guide](https://help.shopify.com/en/manual/custom-data/metafields) covers this in full.

1. In your Shopify admin, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)).
2. Choose where the metafield goes: **Variants** for product metafields, **Customers** or **Orders** for the others.
3. Click **Add definition** and fill in the fields below.
4. Click **Save**.

| Field | What to enter |
| --- | --- |
| **Name** | A name your team will recognise, for example `B2B - MSRP Pricing (RRP)` |
| **Namespace and key** | `sparklayer.` followed by the key, for example `sparklayer.pack_size` or `sparklayer.rrp`. The namespace must be `sparklayer`. |
| **Type** | The data type, for example a text field, JSON or a list of values. The [Metafields](https://docs.sparklayer.io/developers/data/metafields.md) reference gives the type for each setting. |

> **Common mistake: wrong namespace**
>
> In the Shopify admin, the namespace and key are one field, **Namespace and key**. Shopify fills it in from the name you type, starting with `custom.`, so a definition named "B2B - Settings" becomes something like `custom.b2b_settings`. SparkLayer never reads that field. Replace the whole value with the exact SparkLayer namespace and key, for example `sparklayer.settings` (type **JSON**, on **Variants**) or `sparklayer.pack_size` (type **Integer**).

### Set up the sales agent groups metafield

If you use the sales agent groups metafield (`sparklayer.sales_agent_groups`), its definition must be set to **Limit to preset choices**. Each sales agent group is then a choice in a dropdown on the customer. If the metafield takes free text instead, customers can show sync errors.

1. In your Shopify admin, go to **Settings > Custom data** ([open in the Shopify admin](https://admin.shopify.com/settings/custom_data)) and click **Customers**.
2. Open the sales agent groups definition. If there isn't one, click **Add definition** and use the namespace and key `sparklayer.sales_agent_groups`, with a list of single line text as the **Type**.
3. Turn on **Limit to preset choices**.
4. Add each of your sales agent groups as a choice, then click **Save**.

Customers who had sync errors from this metafield sync on the next partial sync. See [Product and customer sync](https://docs.sparklayer.io/help/integrations/data-sync.md#fix-customer-sync-errors).

## Import order history into SparkLayer

You can import historic B2B orders into SparkLayer, so customers see their previous orders when they sign in to their account on your store. Do this after SparkLayer is installed, so the orders sync correctly.

1. Add an order metafield definition with these settings:

   | Field                | Value          |
   | -------------------- | -------------- |
   | **Custom data type** | Order          |
   | **Metafield type**   | `boolean`      |
   | **Namespace**        | `sparklayer`   |
   | **Key**              | `order_import` |

2. On each order you want to import, set the metafield's value to `true`.

3. Make sure each of those orders has the tag `b2b` in Shopify.

Synced orders appear in the Orders section of the SparkLayer Dashboard and are included in reporting.

For a large number of orders, use a bulk import tool such as [Matrixify](https://apps.shopify.com/excel-export-import?st_source=autocomplete). Start from our [sample CSV template](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/example-historic-order-import.csv?v=1738672207), or put the Shopify order ID in the `ID` column in this format:

| ID | Metafield: sparklayer.order\_import \[boolean] | Command |
| --- | --- | --- |
| `[order-id-here]` | `TRUE` | `UPDATE` |

## Set a custom order number

You can show customers your own order number instead of the one Shopify generates, for example to match order numbers from your back-office system (such as an ERP). SparkLayer calls this the **Visible ID**. Customers see it as the order **Reference** in the [My Account](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md).

Add an order metafield with these settings, then enter your order number on each order:

| Field | Value |
| --- | --- |
| **Custom data type** | Order |
| **Metafield type** | `single line text` |
| **Namespace** | `sparklayer` |
| **Key** | `visible_id` |

Orders without a Visible ID show the standard Shopify order number.

## Order data reference (for developers)

This section is technical reference for your developer or integration partner. You don't need it to use SparkLayer.

When SparkLayer sends an order to Shopify, it adds these details to the order:

| Attribute | Notes |
| --- | --- |
| `note` | Order note attribute `sparkCartId`. Mainly for our internal debugging. |
| `note` | Order note attribute `sparkPaymentType`: the payment option used. One of `upfrontPayment`, `paymentOnAccount`, `paymentByInvoice` or `quote`. |
| `tag` | The tag `b2b`, added to every order placed through SparkLayer. |

Each line item also has a `Charged Price` attribute with the final line price. On the order in Shopify, these appear under **Additional details**, and each line item shows its **Charged Price**. 

### Order mapping

How Shopify order fields map to SparkLayer order fields:

| Shopify | SparkLayer |
| --- | --- |
| `processsed_at` | `created_at` |
| `id` | `external_id` |
| `name` | `visible_id` |
| `currency` | `currency_code` |
| `note` | `customer_reference` |
| `customer.id` | `customer_id` |
| `billing_address` | `billing_address` |
| `shipping_lines[0].title` | `packages[0].shipping_name` |
| | `packages[0].shipping_sku` === 'shopify' |
| `shipping_address` | `packages[0].shipping_address` |
| `shopifyOrder.shipping_lines[X].price (SUM)` | `packages[0].total_shipping_.gross` |
| `shopifyOrder.shipping_lines[X].tax_lines.price (SUM)` | `packages[0].total_shipping_.net` |
| `line_items[T].name` | `packages[0].items[T].name` |
| `line_items[T].quantity` | `packages[0].items[T].quantity` |
| `line_items[T].id` | `packages[0].items[T].variant_id` |
| `(T)` | `packages[0].items[T].line_total.gross` |
| `(T)` | `packages[0].items[T].line_total.net` |

## Advanced settings

For customer-level product metafield settings and other advanced options, see [Product rules per customer group](https://docs.sparklayer.io/help/storefront/product-settings.md).