Metafields and data mapping

How it works

Metafields (opens in a new tab) are extra fields you can add to products, customers and orders in Shopify, to store information Shopify doesn't capture by default. Each SparkLayer metafield turns on or configures a specific B2B feature:

Type	What SparkLayer uses them for
Product metafields	Settings for the frontend interfaces, such as pack sizes and RRP prices
Customer metafields	Customer settings, such as credit limits
Order metafields	Order details, such as invoicing information

Setting one up takes two steps: SparkLayer adds the field once, then you fill it in. Keep two things in mind:

Product metafields go on variants. Fill them in on each product variant, never the product, even if the product has only one variant.
Some values are JSON. A few settings, such as credit limits, are written in a set format (JSON), for example {"net_terms":"30_days"}. Their pages have a Build the value form that writes it for you to copy.

Add metafields automatically

SparkLayer can create its metafields in Shopify for you. This is the easiest way to add them, and needs no technical knowledge.

Go to SparkLayer Wholesale,Integrations,Platform (in your Shopify admin).
In the Metafields card (SparkLayer metafields), click Configure.
The Metafield Configuration window lists the metafields you can add for Product and Customer data, such as Pack Size, Reserved DTC Stock Quantity, Restock Date and Stock Location Settings. Click Enable beside each one you want. The metafield shows a green tick.

SparkLayer only reads a metafield once it's enabled here. If you've created a definition yourself in Shopify, enable it here too.

Each metafield you enable is added to Settings,Custom data (opens in your Shopify admin in a new tab) in Shopify and pinned, so it appears at the top of the metafields on each product or customer. Its name starts with B2B -, for example B2B - Pack Size.

To change or remove these metafields, go to Settings,Custom data (opens in your Shopify admin in a new tab) in Shopify.

Fill in metafields

Once a field exists, fill it in whichever way suits how many products or customers you're changing.

One product or customer

Open the product variant, customer or order in Shopify and enter the value in its Metafields card. Click Show all if you can't see the field.

For example, you can set payment terms on a customer, such as {"net_terms":"30_days"}, or a customer-specific discount (Customer % Discount).

Many at once

Shopify's bulk editor shows a metafield as a column, so you can fill in hundreds of products or customers in one table, without opening each one:

In your Shopify admin, go to Products (opens in your Shopify admin in a new tab) or Customers (opens in your Shopify admin in a new tab) and tick the ones to change. To change them all, tick the box at the top of the list.
Click Edit products or Edit customers.
Click Columns and, under Metafields, tick the SparkLayer fields you want, such as B2B - Pack Size.
Type each value. For products, each variant has its own row.
Click Save. If a value is in the wrong format, Shopify highlights it: fix it and click Save again.

See Shopify's guide to editing metafields in bulk (opens in a new tab).

From a spreadsheet

For thousands of rows, or values you already keep in a spreadsheet, use an import app. We recommend Matrixify (opens in a new tab), which reads metafield columns from a spreadsheet and imports them in bulk.

Add metafields by hand

You only need this for a metafield SparkLayer doesn't create for you. Add a metafield definition in Shopify, then fill in its value. Shopify's metafields guide (opens in a new tab) covers this in full.

In your Shopify admin, go to Settings,Custom data (opens in your Shopify admin in a new tab).
Choose where the metafield goes: Variants for product metafields, Customers or Orders for the others.
Click Add definition and fill in the fields below.
Click Save.

Field	What to enter
Name	A name your team will recognise, for example `B2B - MSRP Pricing (RRP)`
Namespace and key	`sparklayer.` followed by the key, for example `sparklayer.pack_size` or `sparklayer.rrp`. The namespace must be `sparklayer`.
Type	The data type, for example a text field, JSON or a list of values. The Metafields reference gives the type for each setting.

Common mistake: wrong namespace

In the Shopify admin, the namespace and key are one field, Namespace and key. Shopify fills it in from the name you type, starting with custom., so a definition named "B2B - Settings" becomes something like custom.b2b_settings. SparkLayer never reads that field. Replace the whole value with the exact SparkLayer namespace and key, for example sparklayer.settings (type JSON, on Variants) or sparklayer.pack_size (type Integer).

Set up the sales agent groups metafield

If you use the sales agent groups metafield (sparklayer.sales_agent_groups), its definition must be set to Limit to preset choices. Each sales agent group is then a choice in a dropdown on the customer. If the metafield takes free text instead, customers can show sync errors.

In your Shopify admin, go to Settings,Custom data (opens in your Shopify admin in a new tab) and click Customers.
Open the sales agent groups definition. If there isn't one, click Add definition and use the namespace and key sparklayer.sales_agent_groups, with a list of single line text as the Type.
Turn on Limit to preset choices.
Add each of your sales agent groups as a choice, then click Save.

Customers who had sync errors from this metafield sync on the next partial sync. See Product and customer sync.

Import order history into SparkLayer

You can import historic B2B orders into SparkLayer, so customers see their previous orders when they sign in to their account on your store. Do this after SparkLayer is installed, so the orders sync correctly.

Add an order metafield definition with these settings:

Field Value
Custom data type Order
Metafield type boolean
Namespace sparklayer
Key order_import
On each order you want to import, set the metafield's value to true.
Make sure each of those orders has the tag b2b in Shopify.

Synced orders appear in the Orders section of the SparkLayer Dashboard and are included in reporting.

For a large number of orders, use a bulk import tool such as Matrixify (opens in a new tab). Start from our sample CSV template (opens in a new tab), or put the Shopify order ID in the ID column in this format:

ID	Metafield: sparklayer.order_import [boolean]	Command
`[order-id-here]`	`TRUE`	`UPDATE`

Set a custom order number

You can show customers your own order number instead of the one Shopify generates, for example to match order numbers from your back-office system (such as an ERP). SparkLayer calls this the Visible ID. Customers see it as the order Reference in the My Account.

Add an order metafield with these settings, then enter your order number on each order:

Field	Value
Custom data type	Order
Metafield type	`single line text`
Namespace	`sparklayer`
Key	`visible_id`

Orders without a Visible ID show the standard Shopify order number.

Order data reference (for developers)

This section is technical reference for your developer or integration partner. You don't need it to use SparkLayer.

When SparkLayer sends an order to Shopify, it adds these details to the order:

Attribute	Notes
`note`	Order note attribute `sparkCartId`. Mainly for our internal debugging.
`note`	Order note attribute `sparkPaymentType`: the payment option used. One of `upfrontPayment`, `paymentOnAccount`, `paymentByInvoice` or `quote`.
`tag`	The tag `b2b`, added to every order placed through SparkLayer.

Each line item also has a Charged Price attribute with the final line price. On the order in Shopify, these appear under Additional details, and each line item shows its Charged Price.

Order mapping

How Shopify order fields map to SparkLayer order fields:

Shopify	SparkLayer
`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`

Advanced settings

For customer-level product metafield settings and other advanced options, see Product rules per customer group.