Product custom fields

International Enhancements for Multi-Storefront

This feature is currently available for Enterprise stores and Partner Sandboxes. If the feature is not working as expected, please contact technical support, as the feature likely needs to be enabled for the individual store. To become an enterprise customer, contact your BigCommerce Customer Service Manager or our support team.

Using the Catalog features of the Admin API, you can localize custom fields for a product in a storefront channel.

You must first create the custom field through the control panel or Create product custom field endpoint of the REST Management API.

You can perform the following:

Set attributes for the custom field:

The setProductCustomFieldsInformation mutation lets you set global values for the store that channels inherit by default. The mutation also lets you set overrides for a channel locale, which will override global store information.
Remove overrides for a channel locale. A channel then inherits global values.
Query custom fields, those set at the global level and the overrides.

For a full schema, see the GraphQL Admin API reference.

Input fields

Setting or removing information requires that you specify ID fields in the input. For more information on how to specify ID fields, see Input fields.

Set product custom fields

The following example sets custom fields for the global store and the specified channel locale.

Request

Response

Example mutation: Set product custom fields

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: UpdateProductCustomFieldsInput!) {
7   product {
8     updateProductCustomFields (input: $input) {
9       product {
10         customFields {
11           edges {
12             node {
13               id
14 
15               # For the global store
16               name
17               value
18 
19               # For the channel locale
20               overrides (context: { channelId: "bc/store/channel/1", locale: "en-US" }) {
21                 edges {
22                   node {
23                   ... on ProductCustomFieldOverridesForChannelLocale {
24                       name
25                       value
26                       isVisible
27                       context {
28                         channelId
29                         locale
30                       }
31                     }
32                   }
33                 }
34               }
35             }
36           }
37         }
38       }
39     }
40   }
41 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "customFieldId": "bc/store/productCustomField/1",
7 
8         // For the global store
9         "name": "Global custom field name",
10         "value": "Global custom field value",
11 
12         // For the channel locale
13         "overrides": [
14           {
15             "channelLocaleOverrides": {
16               "context": {
17                 "channelId": "bc/store/channel/1",
18                 "locale": "en-US"     
19               },
20               "data": {
21                 "name": "Custom field name override",
22                 "value": "Custom field value override",
23                 "isVisible": true
24               }
25             }
26           }
27         ]
28       }
29     ]
30   }
31 }

Remove product custom fields for a locale

The following example removes product custom fields for the specified channel locale.

Omitting the attributes field from the input removes all overrides for the custom fields from the locale.

Request

Response

Example mutation: Remove product custom fields for a locale

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: RemoveProductCustomFieldsOverridesInput!) {
7   product {
8     removeProductCustomFieldsOverrides(input: $input) {
9       product {
10         customFields {
11           edges {
12             node {
13               id
14 
15               # For the global store
16               name
17               value
18 
19               # For the channel locale
20               overrides (context: { channelId: "bc/store/channel/1", locale: "en-US" }) {
21                 edges {
22                   node {
23                     ... on ProductCustomFieldOverridesForChannelLocale {
24                       name
25                       value
26                       isVisible
27                       context {
28                         channelId
29                         locale
30                       }
31                     }
32                   }
33                 }
34               }
35             }
36           }
37         }
38       }
39     }
40   }
41 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "customFieldId": "bc/store/productCustomField/1",
7         "channelLocaleContextData": {
8           "context": {
9             "channelId": "bc/store/channel/1",
10             "locale": "en-US"
11           },
12           "attributes": ["NAME", "VALUE", "IS_VISIBLE"]
13         }
14       }
15     ]
16   }
17 }

Query product custom fields

The following example retrieves custom fields. You can retrieve global information for the store and overrides for the specified channel locale.

Request

Response

Example query: Get product custom fields

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 query {
7   store {
8     product(id: "bc/store/product/111") {
9       customFields {
10         edges {
11           node {
12             id
13 
14             # For the global store
15             name
16             value
17 
18             # For the channel locale
19             overrides (context: { channelId: "bc/store/channel/1", locale: "en-US" }) {
20               edges {
21                 node {
22                   ... on ProductCustomFieldOverridesForChannelLocale {
23                     name
24                     value
25                     isVisible
26                     context {
27                       channelId
28                       locale
29                     }
30                   }
31                 }
32               }
33             }
34           }
35         }
36       }
37     }
38   }
39 }

International Enhancements for Multi-Storefront

Using the Catalog features of the Admin API, you can localize custom fields for a product in a storefront channel.

You must first create the custom field through the control panel or Create product custom field endpoint of the REST Management API.

You can perform the following:

Set attributes for the custom field:

The setProductCustomFieldsInformation mutation lets you set global values for the store that channels inherit by default. The mutation also lets you set overrides for a channel locale, which will override global store information.
Remove overrides for a channel locale. A channel then inherits global values.
Query custom fields, those set at the global level and the overrides.

For a full schema, see the GraphQL Admin API reference.

Input fields

Setting or removing information requires that you specify ID fields in the input. For more information on how to specify ID fields, see Input fields.

Set product custom fields

The following example sets custom fields for the global store and the specified channel locale.

Request

Response

Example mutation: Set product custom fields

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: UpdateProductCustomFieldsInput!) {
7   product {
8     updateProductCustomFields (input: $input) {
9       product {
10         customFields {
11           edges {
12             node {
13               id
14 
15               # For the global store
16               name
17               value
18 
19               # For the channel locale
20               overrides (context: { channelId: "bc/store/channel/1", locale: "en-US" }) {
21                 edges {
22                   node {
23                   ... on ProductCustomFieldOverridesForChannelLocale {
24                       name
25                       value
26                       isVisible
27                       context {
28                         channelId
29                         locale
30                       }
31                     }
32                   }
33                 }
34               }
35             }
36           }
37         }
38       }
39     }
40   }
41 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "customFieldId": "bc/store/productCustomField/1",
7 
8         // For the global store
9         "name": "Global custom field name",
10         "value": "Global custom field value",
11 
12         // For the channel locale
13         "overrides": [
14           {
15             "channelLocaleOverrides": {
16               "context": {
17                 "channelId": "bc/store/channel/1",
18                 "locale": "en-US"     
19               },
20               "data": {
21                 "name": "Custom field name override",
22                 "value": "Custom field value override",
23                 "isVisible": true
24               }
25             }
26           }
27         ]
28       }
29     ]
30   }
31 }

Remove product custom fields for a locale

The following example removes product custom fields for the specified channel locale.

Omitting the attributes field from the input removes all overrides for the custom fields from the locale.

Request

Response

Example mutation: Remove product custom fields for a locale

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 mutation ($input: RemoveProductCustomFieldsOverridesInput!) {
7   product {
8     removeProductCustomFieldsOverrides(input: $input) {
9       product {
10         customFields {
11           edges {
12             node {
13               id
14 
15               # For the global store
16               name
17               value
18 
19               # For the channel locale
20               overrides (context: { channelId: "bc/store/channel/1", locale: "en-US" }) {
21                 edges {
22                   node {
23                     ... on ProductCustomFieldOverridesForChannelLocale {
24                       name
25                       value
26                       isVisible
27                       context {
28                         channelId
29                         locale
30                       }
31                     }
32                   }
33                 }
34               }
35             }
36           }
37         }
38       }
39     }
40   }
41 }

GraphQL variables

1 {
2   "input": {
3     "productId": "bc/store/product/111",
4     "data": [
5       {
6         "customFieldId": "bc/store/productCustomField/1",
7         "channelLocaleContextData": {
8           "context": {
9             "channelId": "bc/store/channel/1",
10             "locale": "en-US"
11           },
12           "attributes": ["NAME", "VALUE", "IS_VISIBLE"]
13         }
14       }
15     ]
16   }
17 }

Query product custom fields

The following example retrieves custom fields. You can retrieve global information for the store and overrides for the specified channel locale.

Request

Response

Example query: Get product custom fields

1 POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2 X-Auth-Token: {{ACCESS_TOKEN}}
3 Content-Type: application/json
4 Accept: application/json
5 
6 query {
7   store {
8     product(id: "bc/store/product/111") {
9       customFields {
10         edges {
11           node {
12             id
13 
14             # For the global store
15             name
16             value
17 
18             # For the channel locale
19             overrides (context: { channelId: "bc/store/channel/1", locale: "en-US" }) {
20               edges {
21                 node {
22                   ... on ProductCustomFieldOverridesForChannelLocale {
23                     name
24                     value
25                     isVisible
26                     context {
27                       channelId
28                       locale
29                     }
30                   }
31                 }
32               }
33             }
34           }
35         }
36       }
37     }
38   }
39 }

1	POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
2	X-Auth-Token: {{ACCESS_TOKEN}}
3	Content-Type: application/json
4	Accept: application/json
5
6	mutation ($input: UpdateProductCustomFieldsInput!) {
7	product {
8	updateProductCustomFields (input: $input) {
9	product {
10	customFields {
11	edges {
12	node {
13	id
14
15	# For the global store
16	name
17	value
18
19	# For the channel locale
20	overrides (context: { channelId: "bc/store/channel/1", locale: "en-US" }) {
21	edges {
22	node {
23	... on ProductCustomFieldOverridesForChannelLocale {
24	name
25	value
26	isVisible
27	context {
28	channelId
29	locale
30	}
31	}
32	}
33	}
34	}
35	}
36	}
37	}
38	}
39	}
40	}
41	}

1	{
2	"input": {
3	"productId": "bc/store/product/111",
4	"data": [
5	{
6	"customFieldId": "bc/store/productCustomField/1",
7
8	// For the global store
9	"name": "Global custom field name",
10	"value": "Global custom field value",
11
12	// For the channel locale
13	"overrides": [
14	{
15	"channelLocaleOverrides": {
16	"context": {
17	"channelId": "bc/store/channel/1",
18	"locale": "en-US"
19	},
20	"data": {
21	"name": "Custom field name override",
22	"value": "Custom field value override",
23	"isVisible": true
24	}
25	}
26	}
27	]
28	}
29	]
30	}
31	}