Import / Export

You can save time by managing metafields in bulk with our spreadsheet import and export tool. 

Export metafields

First choose a metafield type, e.g. products. Then click the "Export" tab. 

Choose the Export type: Shared metafields or Custom metafields.

Choose the "Start export" button. 

Once an export has been started, its progress will be shown in the "Export history" section. 

Exports are deleted after 3 days.

Progress is shown for all recent exports and a link to download the results will be displayed once the process is complete. 

Import metafields

When viewing a resource type, e.g. products, click the "Import" tab. 

You can then choose a file and click the "Start upload" button. 

Progress will then be shown in the "Import history" section. 

Imports are deleted after 3 days.

There are two different import formats, depending on the import type: Shared or Custom.

Shared metafields import format

When importing shared metafields, each row is an item, and each column is a shared metafield.

The column name for each shared metafield should be of the format: "$namespace.$key".


Field Required Notes
id Yes The resource id, e.g. product ID, category ID
$namespace.$key No Include one or more shared metafield columns. The name of the column should be of the format "$namespace.$key", e.g. shared.related_products
mode No To delete a metafield specify a mode column with value "delete"

When assigning a custom resource to a shared metafield, you will need to use it's ID. This can be found in the list view.


Custom metafields import format

When importing custom metafields, each row of the spreadsheet refers to an individual metafield and so requires an identifier of the resource item, i.e. product, as well as the required fields for a metafield.

The supported columns for a custom metafields import are shown below.

We recommend preparing for a metafields import by starting with a recent export spreadsheet

Field Required Notes
id Yes The resource id, e.g. product ID, category ID
namespace Yes This is BigCommerce's way of grouping metafields together to avoid the keys clashing with metafields created by other apps and API users.
key Yes Metafield name
permission_set On creation Allowed values are "read", "write", "read_and_sf_access", "write_and_sf_access" and "app_only". We recommend using "write" or "write_and_sf_access". 
value On creation Once this field is set it can be changed but cannot be set as an empty value, e.g. "" or null.
description No Once this field is set it can be changed but cannot be set as an empty value, e.g. "" or null.
name No This field is ignored. It's included in exports to make it easier to read and identify items
mode No To delete a metafield specify a mode column with value "delete"

To delete a metafield, specify "delete" mode on the appropriate row in column "mode".

Import Errors

If there were any errors when updating a metafield, the status will be updated to "Completed with errors". View the errors by clicking on the red warning triangle icon. The full list of errors can also be viewed by downloading the results spreadsheet. This spreadsheet will include columns that show when an update failed and why it failed.  

Common Errors

"You do not have permission to delete the metafield"

BigCommerce only allows the original API user that created the metafield to delete the metafield. Consider how this metafield was created to identify which app or API account needs to delete the metafield.

"You do not have permission to modify the metafield"

The value field of a metafield can only be updated if permission_set is set to "write" or "write_and_sf_access", or the metafield was created by the app.

The namespace, key, description and permission_set fields can only be updated by the app or API user that created the metafield. 

Unable to update metafield - Invalid field(s): value

The 'value' field cannot be empty. If you need to unset it, you will need to either delete the metafield, or set it to a known "falsey" value that your code can detect, e.g. "null" or "_empty_",

Single-item import/export

Alternatively, if you only want to manage the metafields of a single item, you can create an export from the item view. For example, when editing a product variant, go to the "Import/Export" tab to manage this specific item's metafields in bulk.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us