Links

Data Mapping and Metafields

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
{
"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 this
Example metafield
{
"key": "payment_on_account",
"value": "{\"credit_limit\": 1500,\"balance\": 149}",
"value_type": "json_string",
"namespace": "sparklayer"
}

Order Data

Order data is necessary to synchronise for two reasons:
  1. 1.
    It allows B2B customers to view their order history in their My Account area
  2. 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

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.
We also have a sample CSV template you can start with.
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.