Data Mapping and Metafields
When you install the SparkLayer Connector for Shopify, it will automatically connect to the relevant data it needs. For Shopify, this will be product data and customer data.
- Product Data: By synchronising product data, SparkLayer knows what product pricing to display when a B2B customer is signed in and visits a product page.
- Customer Data: By synchronising customer records, SparkLayer can recognise when a B2B customer signs into your Shopify store;
- Order Data: By synchronising order records, SparkLayer can show order data within the SparkLayer My Account Interface.
This guide acts as a reference point to help you better understand how the two systems map fields to one other.
You can test if SparkLayer is successfully receiving your Shopify product data from the Data Feeds section in the SparkLayer Dashboard. Learn more.
Data is mapped as follows:
Shopify | Spark Layer |
id | external_id |
handle | slug |
title | title |
Shopify | Spark Layer |
id | external_id |
sku | sku |
product_id | identifier[shopify_product_id] |
weight if weight_unit === 'g' | grams |
parent.option<T>.name | variants[T].group |
option<T> | variants[T].value |
parent.status | status * see below |
position === 1 | default |
The Variant Product Image | cart_image_url |
Shopify | SparkLayer |
active | live |
archived | suspended |
draft | pending |
deleted | discontinued |
If you're wanting to set up product packing sizing so your customers can order in predefined units (e.g. 3, 6, 9), please see our guide here.
Customer data from Shopify needs to be synchronised in order for SparkLayer to recognise when a B2B customer signs into your Shopify website. Without the synchronisation, SparkLayer won't be able to render their specific product prices and the ability to purchase.
Important note about customer synchronisation from Shopify
For a customer to be synchronised between Shopify and SparkLayer, please note the following
- The customer must be mapped between the two systems. Either through meta field mapping or via customer tags that you set up in Shopify.
- The customer must have a tag of
b2bassigned to them in Shopify within their customer record (see screenshot below) - If you intend to set up Customer Groups that apply different rules per customer, you'll also need to tag customers with additional tags. You can read our guide here
- At least one valid address must be assigned to their record in Shopify
Tags are added via the Customers admin in Shopify
By default, when you install the SparkLayer Shopify App, this customer synchronisation will happen automatically and no further action should be required unless you are looking to extend the data sent with additional mappings (see below).
You can test if SparkLayer is successfully receiving your Shopify customer data from the Data Feeds section in the SparkLayer Dashboard. Learn more.
Shopify | Spark Layer |
id | external_id |
email | email |
first_name | first_name |
last_name | last_name |
tax_exempt | tax_exempt |
Shopify | Spark Layer |
id | external_id |
first_name | first_name |
last_name | last_name |
company | company |
address1 | address_line1 |
address2 | address_line2 |
city | city |
country_code | country_code |
province_code | region_code |
zip | postcode |
phone | phone |
For customers and product data, fields not mapped above can be mapped via the Shopify
metafield system, giving you flexibility to extend what data you send to SparkLayer. Any meta fields you add must use a namespace of
sparklayerand should map to the corresponding key in the SparkLayer API.For example, to map a field of
'Company Name' with a key named company_name, it would look like this:Example metafield
{
"key": "company_name",
"value": "John & Co DIY Ltd",
"value_type": "string",
"namespace": "sparklayer"
}
To map a custom payment method of
payment_on_account , it would look like thisExample metafield
{
"key": "payment_on_account",
"value": "{\"credit_limit\": 1500,\"balance\": 149}",
"value_type": "json_string",
"namespace": "sparklayer"
}
Order data is necessary to synchronise for two reasons:
- 1.
- 2.It is used for reporting to see the usage of SparkLayer on your Shopify website
This guide walks through how the order mapping works.
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 import historic B2B order data into SparkLayer, allowing customers to see their previous order history once they access their account on your store.
If you're working with the Shopify API, you can use the note_attribute feature of Shopify to assign a special flag that then synchronises specific order(s) with SparkLayer
"note_attributes": [
{
"name": "sparkOrderImport",
"value": "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.ID | Metafield: sparklayer.sparkOrderImport [boolean] | Command |
|---|---|---|
[order-id-here] | TRUE | UPDATE |
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.
Last modified 4mo ago