Metafields

Metafields

Metafields are user defined key-value pairs that developers can attach to BigCommerce data objects. You can use them to add a layer of custom information to products, carts, and more. In most cases, metafields offer specific knowledge that’s needed to fully define or enhance a custom store feature.

Use cases

In the catalog context, you can add metafields to display unique identifiers that customers look for when they make purchasing decisions. For example, for a small batch coffee brand, you might define a metafield on their variant objects to store the roasted on date.

The following list of use cases is an example of what you can do with metafields in a variety of object contexts:

Products

Aggregate data from variants into one product metafield.

Variants

Add information available at the product level, like GTINs or videos.

Categories

Link a category with the matching categories in other languages.

Brands

Use widgets to show different information for each brand.

Carts

Retain subscription settings until the shopper finishes checking out.

Customers

Associate customers with CRM or ERP-style data.

Orders

Save extra fulfillment information.

Locations

Save the shipping options available from that location.

Channels

Associate channels with locations Save an array of languages or other localization features shoppers can toggle between; for example, Canadian storefronts might toggle between English and French.

Supported objects

You can work with metafields using the REST Management API, the GraphQL Storefront API, and the GraphQL Admin API.

Currently, the following objects support metafields:

  • Customers
  • Carts
  • Channels
  • Brands
  • Categories
  • Products
  • Variants
  • Locations
  • Orders

Permissions

The table describes the visibility and writability permissions available for metafield properties.

ValueDescription
app_onlyPrivate to the app that owns the field.
readVisible to other API consumers.
writeOpen for reading and writing by other API consumers.
read_and_sf_accessVisible to other API consumers, including on storefront.
write_and_sf_accessOpen for reading and writing by other API consumers, including on storefront.

Create a metafield

In this example, you’re working with the same small batch coffee brand. To drive sales, the roaster wants to make product variant recommendations to customers based on their order history. Your solution defines a customer metafield that captures the most recent order.

Prerequisites

  • A BigCommerce store
  • Access to the customerId

Steps

Use the Create a customer metafield endpoint to save the description of the most recent variant the customer purchased.

⚠️

The key field has a max character limit of 255 and a minimum of 1. The value field has a max character limit of 65535 characters and a minimum of 1 .

Example request
POST https://api.bigcommerce.com/stores/{store_hash}/v3/customers/{customerId}/metafields
Accept: application/json
Content-Type: application/json
X-Auth-Token: {access_token}
 
{
  "permission_set": "app_only",
  "namespace": "Custom Product Reccomendations",
  "key": "blonde roast",
  "value": " Sunny Collective Blonde Roast, Whole Bean, (4 oz)",
  "description": "Customer's purchase history recommendations"
}

A success response returns a copy of the metafield object to confirm that the metafield is attached to the customer. Your application can now access the most recent purchase the customer made directly from the customer object.

Did you find what you were looking for?
Inventory and location eventsScripts