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:

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


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

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.


  • A BigCommerce store
  • Access to the customerId


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