Metafields and data mapping

How SparkLayer uses metafields

Metafields store information that the BigCommerce admin doesn't usually capture. SparkLayer reads three kinds:

Add product and order metafields

You don't need a developer for product and order metafields. Use a metafields app, such as the approved Metafields Manager (opens in a new tab) app. It can edit metafields on products, variants and orders, but not customers.

You can also use the BigCommerce API: see BigCommerce's guide to product metafields (opens in a new tab).

Things to know

• Product metafields are always added at variant level, even if a product only has one variant.
• Some SparkLayer settings must be entered as JSON, a structured text format. Their pages, such as Product rules per customer group, have a Build the value form that writes it for you to copy.

For the settings each metafield controls, including customer-level product settings, see Product rules per customer group.

Add customer attributes (for your developer)

No BigCommerce app can add customer attributes, so they're created once per store with the BigCommerce API. This means running a command in a terminal. Pass these steps to your developer, or contact our support team if you need help.

After that, the fields appear when you create or edit a customer in BigCommerce, and you fill them in without any code.

1. Find your store hash. It's the part of your admin URL between store- and .mybigcommerce.com. For example, in store-vbnk8wgy6f.mybigcommerce.com, the store hash is vbnk8wgy6f.
2. Create an API account. In your BigCommerce admin, go to Settings,Store-level API accounts and click Create API Account. Choose V2/V3 API token as the Token type, enter a Name you'll recognise (such as SparkLayer Support), and under OAuth scopes, set Customers to modify.
3. Save the credentials. Click Save. BigCommerce shows the credentials and downloads a copy to your computer. You need the Access token.
4. Run the command. Replace YOUR_STORE_HASH and YOUR_STORE_API_TOKEN in the command below, then run it in a terminal. You can remove any attributes you don't need.

curl --request POST \
  --url https://api.bigcommerce.com/stores/YOUR_STORE_HASH/v3/customers/attributes \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: YOUR_STORE_API_TOKEN' \
  --data '[
	{
		"name": "SparkLayer - Price Lists",
		"type": "string"
	},
	{
		"name": "SparkLayer - Payment On Account",
		"type": "string"
	},
	{
		"name": "SparkLayer - Accounting ID",
		"type": "string"
	},
	{
		"name": "SparkLayer - Discount Percentage",
		"type": "number"
	},
	{
		"name": "SparkLayer - Sales Agent Groups",
		"type": "string"
	},
	{
		"name": "SparkLayer - Parent Customer ID",
		"type": "string"
	}
]'

The customer create and edit pages then show a Customer attribute fields section with optional fields for SparkLayer - Price Lists, SparkLayer - Payment On Account, SparkLayer - Accounting ID, SparkLayer - Discount Percentage, SparkLayer - Sales Agent Groups and SparkLayer - Parent Customer ID.

Import past orders

Import past B2B orders into SparkLayer, so customers see their order history when they sign in. Add this metafield to each order:

Each imported order must belong to a customer in a B2B customer group. Add the metafield only after SparkLayer is installed. For a few orders, use a metafields app; for many, use the BigCommerce Order Metafields API.

Imported orders appear in the SparkLayer Dashboard and its order reports.

If SparkLayer was installed on your store before 14 November 2024, you may need to ask our support team to re-save your BigCommerce integration. Re-saving registers the webhooks that tell SparkLayer when a metafield is added to an order.

Show your own order numbers

Show customers your own order number, such as the one from your ERP, instead of the BigCommerce order number. Customers see it as the order Reference in their My Account area. Add this order metafield:

Orders without a visible_id show the standard BigCommerce order number.