Import / Export
Save time by managing metafields in bulk with the spreadsheet import and export tool.
Export metafields
First choose a resource type, such as products. Then click the "Export" tab.
Choose the export type: Shared metafields or Custom metafields.
Choose "Start export".
Once an export starts, its progress appears in the "Export history" section.
Exports are deleted after 3 days.
Progress is shown for all recent exports. A link to download the results appears when the process is complete.
Import metafields
When viewing a resource type, such as products, click the "Import" tab.
Choose a file and click "Start upload".
Progress appears 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, use its ID. You can find the ID 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 an error occurs while updating a metafield, the status changes to "Completed with errors". View the errors by clicking the red warning triangle, or download the results spreadsheet. The spreadsheet includes columns showing which update failed and why.
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, delete the metafield or set it to a known "falsy" value that your code can detect, such as "null" or "_empty_".
Single-item import/export
If you only want to manage one item's metafields, create an export from the item view. For example, when editing a product variant, open the "Import/Export" tab to manage that item's metafields in bulk.
