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.
