---
title: Shopify Metafields & Data Mapping
slug: shopify-metafields
description: Learn how to customize your Shopify store's functionality and appearance using metafields with this comprehensive document. Discover how to set up and populate metafields, including product and customer metafields. Gain insights on important consideration
docTags:
createdAt: 2023-06-18T07:25:01.000Z
---
## Introduction
:::hint{type="success"}
**See what's possible with metafields**
To see all available metafields for SparkLayer, please see our [Metafields](docId\:OTLHhi8sQ6oS4PAt23-8H) guide.
:::
Metafields help you to customise the functionality and appearance of your Shopify store by letting you save specialised information that isn't usually captured in the Shopify admin. You can use metafields for internal tracking, or to display specialised information on your online store in a variety of ways. For full details, please refer to this [official Shopify guide](https://help.shopify.com/en/manual/custom-data/metafields).
In the context of SparkLayer, metafields are used to capture additional B2B data that you can then use in a variety of ways:
| Type | Details |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Product metafields` | Updating the [Frontend Interfaces](docId\:ccZ1vnH0O6D_722w35Xpa) by adding configurations such as [pack sizing](docId\:CmxfrPgjQxfz9vJzTVv0D), [RRP prices](docId\:S_VTlJBorGmnwjjfSMom9), and more |
| `Customer metafields` | Updating a customer's information by adding information such as [credit limits](docId\:yWm70oQUosyKOoIqb4Z4G) |
| `Order metafields` | Updating an order with [invoicing information](docId\:yWm70oQUosyKOoIqb4Z4G) |
:::hint{type="warning"}
**Important considerations**
In order for SparkLayer to work with Shopify metafields, please note the following:
- **Product metafields**
Metafields are always added at the product variant level, even if the product only comes in a single variant.
- **JSON data**
Some SparkLayer settings require metafields to be set up as JSON strings. These will need to be carefully added, making sure the formatting is set correctly.
:::
***
## Automatically adding metafields
Within the [SparkLayer Dashboard](https://app.sparklayer.io/configuration/integrations/platform), you can speed up the creation of metafields using our built-in tool to automatically configure them.
::::Tabs
:::Tab{title="🛍️ Using Shopify"}
To get started, go to **Integrations, Platform Connection** and click **Configure** within the **Configure metafields** section. You'll then see all available metafields that can be configured for **Product** and **Customer** data.
When a metafield is enabled, this will automatically be added to the [Custom Data](https://admin.shopify.com/settings/custom_data) section of your Shopify admin and will be 'pinned' for easy access when configuring metafields for products or customers.
Any metafields automatically created by SparkLayer in this way will be prefixed with `B2B - [name]` for example `B2B - Pack Size`
Should you need to modify or remove metafields, you can manage this via the [Custom Data](https://admin.shopify.com/settings/custom_data) section within your Shopify store.
:::
::::
***
## Manually adding metafields
:::hint{type="info"}
**Please note**
Shopify has built-in ways to set up metafields and we recommend referring to their [official Shopify guide](https://help.shopify.com/en/manual/custom-data/metafields) on the best ways to do this.
:::
Within your Shopify store, navigate to **Settings** and click **Custom Data** and you'll see an interface similar to the below.
In this example, you can see how [RRP (MSRP) pricing](docId\:S_VTlJBorGmnwjjfSMom9) is set up at a variant level and we've also included a video below to see the full steps.
::embed[]{url="https://www.youtube.com/embed/Duue-ZGKp3A"}
### Setting up product metafields
:::hint{type="success"}
**See what's possible with product metafields**
To see all available metafields for SparkLayer, please see our [Metafields](docId\:OTLHhi8sQ6oS4PAt23-8H) guide.
:::
:::hint{type="warning"}
**Metafields at a variant level**
Generally speaking, in the context of SparkLayer, all metafields are added at the [variant level](https://admin.shopify.com/settings/custom_data/productvariant/metafields) not the product level. This is very important to remember when configuring any metafields that you're looking to add.
:::
:::Iframe{iframeHeight="0" code=""}
:::
When setting up metafields in Shopify, you'll be required to specify the following at a minimum:
| Item | Details |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `Metafield type` | This sets the data type, e.g. a text field, JSON, a selection of values |
| `Namespace` | This defines the category and naming convention of the metafield. In the case of SparkLayer, this must be set as `sparklayer` |
| `Key` | This defines the key to use, e.g. `pack_size` |
| `Value` | This is then added against a product variant within Shopify (see below) |
When you're setting up the Namespace and Key via the Shopify admin, you'll be required to "combine" this in the "Namespace and key" field. In our example below, we've illustrated how this works for [pack sizing](docId\:CmxfrPgjQxfz9vJzTVv0D), entered as `sparklayer.pack_size`.
:::Iframe{iframeHeight="0" code=""}
:::
### Setting up customer metafields
:::hint{type="success"}
**See what's possible with customer metafields**
To see all available metafields for SparkLayer, please see our [Metafields](docId\:OTLHhi8sQ6oS4PAt23-8H) guide.
:::
Customer metafields work in just the same way as product metafields (see above) and, once they are setup within Shopify, you can navigate to any customer record and add or edit data as required. In our example below, we've set up [payment terms](docId\:yWm70oQUosyKOoIqb4Z4G), a [sales agent group](docId\:Uw8mDbMEfwWKqZrVB5CqX), and a [customer-specific discount](docId\:v8dVUcJ7Ju0fH7BvINrEw).
### Populating metafields
Once you've set up metafields, you can navigate to a product, customer, or order record within Shopify and add your SparkLayer settings within the fields shown.
***
## Importing metafields in bulk
Currently, Shopify offers no "built-in" way to bulk import metafield data at a variant-level so it's necessary to use third-party apps to get around this. One of the most recommended, is an app called [Matrixify](https://apps.shopify.com/excel-export-import) which allows you to easily "map" metafield data and import in bulk.
***
## Order Data
:::hint{type="success"}
**See what's possible with order metafields**
To see all available metafields for SparkLayer, please see our [Metafields](docId\:OTLHhi8sQ6oS4PAt23-8H) guide.
:::
When an order is passed to Shopify, the following attributes are attached to the order:
| Attribute | Notes |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `note` | Order Note: `sparkCartId` This is added as an **order note.** This is primarily for internal use for debugging |
| `note` | Order Note: `sparkPaymentType` This is added as an **order note.** This contains the name of the payment option used: * upfrontPayment
* paymentOnAccount
* paymentByInvoice
* quote |
| `tag` | A tag of `b2b` is added to any order placed via SparkLayer |
On each line item, there is also a `Charged Price` attribute which contains the final line item price.
### Order Mapping
| Shopify | Spark Layer |
| ------------------------------------------------------ | ---------------------------------------- |
| `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` |
### Order history: importing orders into SparkLayer
It's possible to import historic B2B order data into SparkLayer, allowing customers to see their previous order history once they access their account on your store.
To do this apply a metafield as shown below:
| Item | Details |
| ------------------ | --------------------------------------- |
| `Custom data type` | Order |
| `Metafield type` | This must be set as an `boolean` |
| `Namespace` | This must be set as `sparklayer` |
| `Key` | This must be set as `order_import` |
| `Value` | This must be set as a boolean of `true` |
Any orders that are imported this way must also have a tag of `b2b` assigned to them within Shopify.
If you're working with a large data set and would prefer to do this manually, you can instead use order metafields within Shopify to do this. Our recommendation is to use a bulk import tool such as [Matrixify](https://apps.shopify.com/excel-export-import?st_source=autocomplete) to manage this more quickly. When importing using this tool, you can use the format below simply by adding the Shopify order ID in the `ID` column.
We also have a [sample CSV template](https://cdn.shopify.com/s/files/1/0612/7602/9065/files/example-historic-order-import.csv?v=1738672207) you can start with.
| ID | Metafield: sparklayer.order\_import \[boolean] | Command |
| ----------------- | ---------------------------------------------- | -------- |
| `[order-id-here]` | `TRUE` | `UPDATE` |
:::hint{type="warning" attributes="[object Object]"}
**Please note**
The note attribute must be added to the order **after** SparkLayer is installed for the order to be synchronised correctly. Orders synced in this way can then be reported upon and will appear in the Orders section of the SparkLayer Dashboard.
:::
### Order ID ("Visible ID") and setting a custom order number
It's possible to use a custom order ID instead of the standard order ID generated from Shopify. A typical use-case is customising the Order ID to match order numbers generated from a back-office system (e.g. an ERP), ensuring consistency across systems.
When the "Visible ID" is set, this will then take effect when the customer views their orders from the [My Account Interface](docId\:lQXaNI7IVDqna09D9soAP).
| Item | Details |
| ------------------ | ------------------------------------------ |
| `Custom data type` | Order |
| `Metafield type` | This must be set as an `single line text ` |
| `Namespace` | This must be set as `sparklayer` |
| `Key` | This must be set as `visible_id` |
:::hint{type="warning" attributes="[object Object]"}
**Please note**
If you're using the "Visible ID" configuration, any orders that do not have this populated will fallback to the standard Shopify order number.
:::
***
## Advanced settings
To learn about more advanced settings, including customer-level product metafield settings, please see [Product Settings](docId\:Cm9B1I6Cz0vOlc67g-fJI)