website logo
SupportDashboardAbout SparkLayerSchedule Demo
📘Help Docs
⚙️Tech Docs
Navigate through spaces
⌘K
👋Introduction
How SparkLayer Works
Getting Started
📣Useful Links
What's New!
Roadmap
Support
Try our Demo
Troubleshooting
Policies & Data
🖥️Frontend
⭐Features
⚒️Backend
📊Dashboard
🌐Integrations
Docs powered by
Archbee
Integrations
Shopify

Shopify Metafields & Data Mapping

Introduction

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






How to add metafields to Shopify

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.

Document image


Setting up product metafields

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.

<video class="full-screen-video__media" preload="none" autoplay="" loop="" muted="" playsinline="" webkit-playinginline="">
    <source src="https://www.sparklayer.io/assets/videos/shopify-metafields.mp4" type="video/mp4">
</video>


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.

<video class="full-screen-video__media" preload="none" autoplay="" loop="" muted="" playsinline="" webkit-playinginline="">
    <source src="https://www.sparklayer.io/assets/videos/shopify-metafields2.mp4" type="video/mp4">
</video>


Setting up customer metafields

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.

Document image


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.

Document image







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.






Order Data

Document image


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

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 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.






Advanced settings

To learn about more advanced settings, including customer-level product metafield settings, please see Product Settings

Updated 04 Sep 2023
Did this page help you?
PREVIOUS
Shopify Markets & Currencies
NEXT
Uninstalling & Transferring accounts
Docs powered by
Archbee
TABLE OF CONTENTS
Introduction
How to add metafields to Shopify
Setting up product metafields
Setting up customer metafields
Populating metafields
Important considerations
Order Data
Order Mapping
Importing historic orders into SparkLayer
Advanced settings
Docs powered by
Archbee