Data Mapping and Metafields

Search…
Introduction
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.
Product Data
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:
Product Parent
Shopify
Spark Layer
id
external_id
handle
slug
title
title
Product Variants
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
Product Status
Shopify
SparkLayer
active
live
archived
suspended
draft
pending
deleted
discontinued
Product Pack Sizing
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
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 b2b assigned 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 
Customer Address Mapping
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
Meta Field Mapping
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
1
{
2
  "key": "company_name",
3
  "value": "John & Co DIY Ltd",
4
  "value_type": "string",
5
  "namespace": "sparklayer"
6
}
Copied!
To map a custom payment method of payment_on_account , it would look like this
Example metafield
1
{
2
  "key": "payment_on_account",
3
  "value": "{\"credit_limit\": 1500,\"balance\": 149}",
4
  "value_type": "json_string",
5
  "namespace": "sparklayer"
6
}
Copied!
Order Data
Order data is necessary to synchronise for two reasons:
1.It allows B2B customers to view their order history in their My Account area​
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.
Order Note Attributes
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:
upfrontPayment
paymentOnAccount
paymentByInvoice
quote
hokodoPayment
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
​
Importing historic orders into SparkLayer
To import historic B2B order data into SparkLayer, you can use the note_attribute feature of Shopify. 
1
"note_attributes": [
2
  {
3
    "name": "sparkOrderImport",
4
    "value": "true"
5
  }
6
]
Copied!
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.
The Shopify Storefront User Flow
Uninstalling or Transferring Accounts
Last modified 2mo ago
Copy link
Contents