API

We provide an API so that you can manage your metafields imports & exports programmatically. This can be helpful when integrating with your internal systems.

This feature is available for stores on our Enterprise plan.

For individual metafields, we recommend using BigCommerce's own APIs, e.g. for product metafields.

Authentication

The API is authenticated by way of Bearer token in the Authrorization header, e.g.

Authorization: Bearer {auth_token}

Tokens can be managed from within the Settings > API Tokens page of the app.

Each token is only visible immediately after creation. If lost, a new token can be generated

Postman

We provide a Postman collection to make validating API calls easier.

Export metafields

Get Export History

GET https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/export/{resource}/history

Retrieves export history for a given resource type.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant

Response example

{
  "data": [
    {
      "id": 1,
      "started_at": "2025-08-13T09:28:01.000000Z",
      "finished_at": "2025-08-13T09:28:14.000000Z",
      "status": "completed",
      "items_processed_count": 44,
      "progress_percent": 100,
      "errors": [
        "ID: 1 - Invalid value"
      ],
      "type": "shared",
      "download_url": "https://path-to-file.csv"
    }
  ]
}

Get Export Estimate

GET https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/export/{resource}/estimate

Returns an estimated record count for an export with filters applied.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant

Response example

{
  "data": {
    "count": 1250
  }
}

Generate Export

POST https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/export/{resource}

Starts a new metafields export.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant

Body

application/json

Property Description Type Required
exportType Whether to export shared or custom metafields.

String

Allowed values: custom shared

Yes
availability Filter product & variant metafield exports by the product's availability

String

Allowed values:

available disabled preorder


 No
brand_id Filter product & variant metafield exports by the product's brand Integer No
categories:in Filter product metafields by the product's categories Integer[] No
category_id:in Filter category metafields by the categories' IDs Integer[] No
channel_id

Filter category metafields by the Channel ID.

Cannot be used to filter products by channel assignment

 Integer No
company:in Filter customer metafields by the Company Name. Should be exact company name. String No
condition Filter product and variant metafields by the product's condition.

String

Allowed values: new used refurbished

 No
customer_group_id:in Filter customer metafields by the customers group

String

Comma-separated string of customer group IDs

 No
date_created:max Filter customer metafields by the maximum date the customer was created String No
date_created:min Filter customer metafields by the minimum date the customer was created. String No
date_modified:max Filter product & variant metafields by the modified date

String

2025-01-15 or 2025-01-15T00:03:17Z

 No
date_modified:min Filter product & variant metafields by the modified date

String

2025-01-15 or 2025-01-15T00:03:17Z

 No
id Filter product & variant metafields by the product ID Integer No
id:max Filter product & variant metafields by the maximum product ID Integer No
id:min Filter product & variant metafields by the minimum product ID Integer No
is_visible Filter product & variant metafields by the products visibility Boolean No
keyword Filter product & variants metafields by keyword match against the products name, description and SKU fields String No
max_date_created Filter order metafields by maximum date created of the order

String

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00

 No
max_date_modified Filter order metafields by the maximum date modified of the order

String

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00

 No
max_id Filter order metafields by the maximum ID of the order Integer No
max_total Filter order metafields by the maximum order total

Float

e.g. 39.99

 No
min_date_created Filter order metafields by the minimum date created of the order

String

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00

 No
min_date_modified Filter order metafields by the minimum date modified of the order

String

RFC-2822: Thu, 20 Apr 2017 11:32:00 -0400

ISO-8601: 2017-04-20T11:32:00.000-04:00

 No
min_id Filter order metafields by the minimum ID of the order Integer No
min_total Filter order metafields by the maximum order total.

Float

e.g. 39.99

 No
name:like Filter category & customer metafields by the customer name. Supports partial match String No
status_id:in Filter order metafields by the status of the order.

Int

Allowed Values

 No
tree_id:in Filter category metafields by the Category Tree ID

String

Comma-separated list of Tree IDs

 No

Body example

{
  "exportType": "shared",
  "categories:in": [21]
}

Response example

{
  "data": {
    "id": 456
  }
}

Get Export

GET https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/export/{resource}/{export_id}

Get the details of an export.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant
export_id path The ID of the export

Response example

{
  "data": {
    "id": 456,
    "started_at": "2025-08-13T09:28:01.000000Z",
    "finished_at": "2025-08-13T09:28:14.000000Z",
    "status": "completed",
    "items_processed_count": 44,
    "progress_percent": 100,
    "errors": [
      "ID: 1 - Invalid value"
    ],
    "type": "shared",
    "download_url": "https://path-to-file.csv"
  }
}

Download Export

GET https://metafields.space48/api/v1/stores/{store_hash}/metafields/export/{resource}/{export_id}/download

Downloads the exported metafields CSV file.

We recommend using the download URL provided on the export object, but we provide this endpoint for convenience.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant
export_id path The ID of the export

Cancel Export

DELETE https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/export/{resource}/{export_id}/batch

Cancels an active export process.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant
export_id path The ID of the export

Import metafields

Get Import History

GET https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/import/{resource}/history

Retrieves import history for a given resource type.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant

Response example

{
  "data": [
    {
      "id": 1,
      "started_at": "2025-08-13T09:28:01.000000Z",
      "finished_at": "2025-08-13T09:28:14.000000Z",
      "status": "completed",
      "items_processed_count": 44,
      "progress_percent": 100,
      "errors": [
        "ID: 1 - Invalid value"
      ],
      "type": "shared",
      "download_url": "https://path-to-file.csv"
    }
  ]
}

Generate Import

POST https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/import/{resource}

Starts a new metafields import from a CSV file.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant

Form Data

Property Description Type
files

CSV File.

Note that a single file is expected.

 .csv file
importType Whether to import spreadsheet as custom metafields or shared metafields

String

Allowed values: custom shared

Response example

{
  "data": {
    "id": 321
  }
}

Get Import

GET https://metafields.space48.com/api/v1/stores/{store_hash}/metafields/import/{resource}/{import_id}

Get the details of an import.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant
import_id path The ID of the import

Response example

{
  "data": {
    "id": 321,
    "started_at": "2025-08-13T09:28:01.000000Z",
    "finished_at": "2025-08-13T09:28:14.000000Z",
    "status": "completed",
    "items_processed_count": 44,
    "progress_percent": 100,
    "errors": [
      "ID: 1 - Invalid value"
    ],
    "type": "custom",
    "download_url": "https://path-to-file.csv"
  }
}

Download Import Results

GET https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/import/{resource}/{import_id}/download

Downloads the import results CSV file.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant
import_id path The ID of the import

Cancel Import

DELETE https://metafields.space48apps.com/api/v1/stores/{store_hash}/metafields/import/{resource}/{import_id}/batch

Cancels an active import process.

Params

Param Location Description
store_hash path The unique identifier of your BigCommerce Store
resource path

The type of the metafield.

Allowed values: brand category channel customer location order product variant
import_id path The ID of the import
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