# Metafields and data mapping

URL: https://docs.sparklayer.io/help/platforms/bigcommerce/metafields
Applies to: BigCommerce

Use BigCommerce metafields and customer attributes with SparkLayer for pack sizes, RRP and credit limits, import past orders and set custom order numbers.

> **Quick summary**
>
> - Metafields are optional. You don't need any to install SparkLayer or start taking B2B orders: add them only when you want a feature that uses one, such as pack sizes or credit limits.
> - Metafields hold extra B2B data in BigCommerce, such as a product's pack size or RRP. Customer settings, such as credit limits, use customer attributes instead.
> - Add product and order metafields with an app such as [Metafields Manager](https://www.bigcommerce.co.uk/apps/metafields-manager-by-space-48/), or the BigCommerce API.
> - Customer attributes for SparkLayer have to be created once per store with the BigCommerce API. This is a technical task for your developer, or [contact our support team](https://docs.sparklayer.io/help/support.md) for help.

## How SparkLayer uses metafields

[Metafields](https://docs.sparklayer.io/developers/data/metafields.md) store information that the BigCommerce admin doesn't usually capture. SparkLayer reads three kinds:

| Type | What SparkLayer uses it for |
| --- | --- |
| **Product metafields** | Settings for the [frontend interfaces](https://docs.sparklayer.io/help/storefront/interfaces.md), such as [pack sizes](https://docs.sparklayer.io/help/storefront/quantity-rules.md) and [RRP prices](https://docs.sparklayer.io/help/pricing/pricing-display.md). |
| **Customer attributes** | Customer settings, such as [credit limits](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md). |
| **Order metafields** | [Invoicing information](https://docs.sparklayer.io/help/ordering/credit-net-terms-and-invoicing.md) for an order. |

## 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](https://www.bigcommerce.co.uk/apps/metafields-manager-by-space-48/) 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](https://developer.bigcommerce.com/docs/rest-catalog/products/metafields).

## 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](https://docs.sparklayer.io/help/storefront/product-settings.md), 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](https://docs.sparklayer.io/help/storefront/product-settings.md).

## 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](https://docs.sparklayer.io/help/support.md) 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.

```bash
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:

| Field | Value |
| --- | --- |
| **Namespace** | `sparklayer` |
| **Key** | `order_import` |
| **Value** | The string `true` |

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](https://docs.sparklayer.io/help/support.md) 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](https://docs.sparklayer.io/help/storefront/interfaces/my-account.md) area. Add this order metafield:

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

Orders without a `visible_id` show the standard BigCommerce order number.