Shopify Metafields & Data Mapping
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.
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 by adding configurations such as pack sizing, RRP prices, and more |
Customer metafields | Updating a customer's information by adding information such as credit limits |
Order metafields | Updating an order with invoicing information |
Shopify has built-in ways to set up metafields and we recommend referring to their official Shopify guide on the best ways to do this.
Metafields at a variant level Generally speaking, in the context of SparkLayer, all metafields are added at the variant level not the product level. This is very important to remember when configuring any metafields that you're looking to add.
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, entered as sparklayer.pack_size.
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, a sales agent group, and a customer-specific discount.
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.
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.
When an order is passed to Shopify, the following note attributes are attached to the order:
Attribute | Notes |
sparkCartId | Internal Use for debugging |
sparkPaymentType | Contains the name of the payment option used:
|
On each line item, there is also a Charged Price attribute which contains the final line item price.
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 |
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 sparkOrderImport |
Value | This must be set as a boolean of true |
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 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 you can start with.
ID | Metafield: sparklayer.sparkOrderImport [boolean] | Command |
[order-id-here] | TRUE | UPDATE |
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.
To learn about more advanced settings, including customer-level product metafield settings, please see Product Settings