BigCommerce API 2026: How To Create, Update and Delete a Category Metafield

Today Beehexa will show you How To Create, Update and Delete a Category Metafield. Please read the blog post carefully and watch the video to understand the steps and necessary notes. Let’s get started!

I. Create a Category Metafield.

First of all, we need to check the BigCommerce store to see all the categories that are available right now. Then I have to get the id of the category in which you want to create a new Category Metafields.

As you can see, we have a Category named Garden with ID 19.

Now We will create a new Category Metafield in BigCommerce using Postman.

So, Log in Postman account and then choose a workspace.

Click the Plus button to open a request tab

Select POST and add this URL :

https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/categories/{category_id}/metafields

Replace {store_hash} with the store hash of your BigCommerce store

Replace {category_id} with the category ID you want to delete

when you create a Category Metafield, there are some required Fields:

• permission_set
• namespace
• key
• value

And Read-Only Fields

• id

Each order, product, category, variant, or Category metafield may contain a maximum of 250 metafields per client ID. Visit the Help Center for more information on Platform Limits.

1. In the Header section

You need to fill in the information, including:

• Accept: application/json 

• Content-Type: application/json 

• X-Auth-Token: {access_token}

2. In the Body section

Click on “raw” tofill in the data; remember to change the “text” to “JSON.” Then add the code in the box.

To create a category metafield, you need to declare the following information:

• Id: Unique ID of the Metafield. (Read-Only)

Example: 6

• Permission_set: Determines the visibility and writeability of the field by other API consumers

If you set the value as “app_only”, “Read” and “read_and_sf_access”, you can not update the category metafield.

• Namespace: Namespace for the metafield, for organizational purposes. The developer sets this. Required for POST. (>= 1 characters<= 64 characters)

Example: Store Locations

• Key: The name of the field, for example: location_id, color. Required for POST. (>= 1 characters<= 64 characters)

Example: Location

• Value: The field’s value, for example 1, blue. Required for POST. (>= 1 characters<= 65535 characters)

Example: 4HG

• description: Description of the metafields.(>= 0 characters<= 255 characters)

Example: Location in the store

• Resource_type: The type of resource with which the metafield is associated.

Allowed values: category/Category metafield/product/variant

• Resource_id: The ID for the resource with which the metafield is associated.(>= 0<= 10000000000)

Example: 111

• Date_created: Date and time of the metafield’s creation. (Read-Only)

Example: 2022-12-07T20:14:17+00:00

• Date_modified: Date and time when the metafield was last updated. (Read-Only)

Example:2022-12-07T20:14:17+00:00

Read-Only Fields are the fields in which you can not change information after creating category metafield.

Example:

{
  "permission_set": "write",
  "namespace": "Main Store Locations",
  "key": "Location",
  "value": "3NC",
  "description": "Location in the Store",
  "resource_type": "category",
  "resource_id": 19,
  "date_created": "2022-12-07T20:14:17+00:00",
  "date_modified": "2022-12-07T20:14:17+00:00"
}

Response: The API will return the data like this.

{
    "data": {
        "Id": 7,
        "key": "Location",
        "value": "3NC",
        "namespace": "Main Store Locations",
        "permission_set": "write",
        "resource_type": "category",
        "resource_id": 22,
        "description": "Location in the Store",
        "date_created": "2022-12-07T03:58:24+00:00",
        "date_modified": "2022-12-07T03:58:24+00:00"
    },
    "meta": {}

II. Update a Category Metafields

Select PUT and add this URL :

https://api.bigcommerce.com/stores/f2n6r1gvea/v3/catalog/categories/{category_id}/metafields/{metafield_id}

In addition to the store hash and category id, here you need to provide the category metafield ID that you want to update.

1. In the Header section

• Accept application/json
• Content-Type: application/json
• X-Auth-Token: Access token

2. In the Body section

You can change information like Key, Namespace, description, and value.

Example

{
  "permission_set": "write",
  "namespace": "Beehexa Store color",
  "key": "color",
  "value": "3NC",
  "description": "This is something different",
}

Response: The API will return the data like this.

{
    "data": {
        "Id": 7,
        "key": "color",
        "value": "3NC",
        "namespace": "Beehexa Store color",
        "permission_set": "write",
        "resource_type": "category",
        "resource_id": 22,
        "description": "This is something different",
        "date_created": "2022-12-07T03:58:24+00:00",
        "date_modified": "2022-12-07T03:58:24+00:00"
    },
    "meta": {}

III. Delete a Category Metafield

DELETE: https://api.bigcommerce.com/stores/f2n6r1gvea/v3/catalog/categories/{category_id}/metafields/{metafield_id}

Replace {metafield_id} with your metafield ID you want to delete

In the Header section

• Accept application/json
• Content-Type: application/json
• X-Auth-Token: Access token

Skip the Body part, then click send button to send the request

The API will delete all the data; all you can see is an empty box

In conclusion, the above are all steps to create, update and delete a Category Metafield using BigCommerce API

Please comment below or refer to our BigCommerce API documentation if you have any questions.

Finally, I hope you can do it!