label

name

sort_order

sort

type

storefront_name

Controls the number of items per page in a limited (paginated) list of products.


limit

Specifies the page number in a limited (paginated) list of products.

page

The error title describing the particular error.

Data about the response, including pagination and collection totals.


Returns as an object for modifier types that have configuration.

Returns as an empty array for multiple choice modifiers; for a list of multiple choice types, see [Shared Options and Modifiers Overview](/beta/shared-options-modifiers).

Schema depends on the modifier type. Click on the modifier type to view the schema.


The earliest date and time allowed to be entered on the date option, as an ISO-8601 formatted string.

The latest date and time allowed to be entered on the date option, as an ISO-8601 formatted string.

The type of limit that is allowed to be entered on a date option.

Flag to limit the dates allowed to be entered on a date option. If false, ignores `date_earliest_value` and `date_latest_value` and sets them to the default value.

The default value. 

Shown on a date and time option as an ISO-8601–formatted string, or on a text option as a string.


Date field

Flag for setting the checkbox to be checked by default.

Checkbox

The maximum size for a file that can be used with the file upload option.

The kind of restriction on the file types that can be uploaded with a file upload option. 

Values: 
`specific`: restricts uploads to particular file types.
`all`: allows all file types.


A list of other file types allowed with the file upload option. Non-empty if `file_types_supported` is includes `"other"`.

The type of files allowed to be uploaded if the `file_type_mode` is set to `specific`.

| Enum values for file types | Description |
|-|-|
| `images` | Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). |
| `documents` | Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). |
| `other` | Allows file types defined in the `file_types_other` array. |


File upload

The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string.

Flag to validate the length of a text input. If false, ignores `text_min_length` and `text_max_length`.

The maximum length allowed for a text option.

The minimum length allowed for a text option.

Text field

Flag to validate the length of a multi-line text input. If false, ignores `text_min_length` and `text_max_length`.

Flag to validate the maximum number of lines allowed on a multi-line text input. If false, ignores `text_max_lines`.

The maximum length allowed for a multi line text option.

The maximum number of lines allowed on a multi-line text input.

The minimum length allowed for a multi-line text option.

Multi-line text field

The highest allowed value for a number option if `number_limited` is true.

Flag to limit the input on a number option to whole numbers only.

The type of limit on values entered for a number option.

Flag to limit the value of a number option. If false, ignores `number_lowest_value`, `number_highest_value`, and `number_limit_mode`.

The lowest allowed value for a number option if `number_limited` is true.

Numbers-only text field

Empty array

Total number of items in the collection response.


The page you are currently on within the collection.


Pagination links for the previous and next parts of the whole collection.


Link to the current page returned in the response.


Link to the next page returned in the response.


Link to the previous page returned in the response.


The amount of items returned in the collection per page, controlled by the limit parameter.


Total number of items in the result set.


The total number of pages in the collection.


The unique name identifying the shared modifier in the control panel. Name is unique within a store.

Whether or not this shared modifier is required or not at checkout.

The text display identifying the shared modifier on the storefront.

Type of shared modifier. 

Each type has a unique display style on the storefront. 

Different types may have different data for available values; see the `values` field.

Some types include additional information for you to configure; see the `config` field.

For an explanation of each type, see the [Overview](/beta/shared-options-modifiers).


The unique numeric ID of the value; increments sequentially.

Type of shared entity- modifier or option. Always returns as `modifier` for modifier endpoints.

Data describing modifier values, based on the type of modifier. 

Returns as an empty array for modifiers that aren't checkbox or multiple choice; for an explanation of types, see the [Shared Options and Modifiers Overview](/beta/shared-options-modifiers).


Number of products that use the shared modifier.

The unique numeric ID of the modifier value; increments sequentially.

The flag for preselecting a value as the default on the storefront. Up to one default per modifier. This field is not supported for swatch modifiers.

The unique text display within one option identifying the value on the storefront. Unique within a modifier.

The order in which the value displays on the storefront and in response bodies.

Additional data describing values for swatch and checkbox modifier types. 

Returned in the response for checkbox modifiers, but not needed in requests for checkbox modifiers.


Swatch

Determines which value is considered to be the checked state.

Type of shared entity- modifier or option. Always returns as `variant_option` for option endpoints.

An array of product IDs for the products assigned to the option.

Number of products that use the shared option.

The unique name identifying the shared option in the control panel. Name is unique within a store.

The text display identifying the shared option on the storefront.

Type of shared option. 

Each type has a unique display style on the storefront. 

For an explanation of each type, see the [Overview](/beta/shared-options-modifiers).


The unique numeric ID of the option value; increments sequentially.

The flag for preselecting a value as the default on the storefront. Up to one default per option. This field is not supported for swatch options.

The unique text display within one option identifying the value on the storefront. Unique within an option.

The order in which the value displays on the storefront or in response bodies.

Additional data describing values for swatch option types.


Contains up to three hexidecimal color keys or an `image_url`, which is a full image URL path including the protocol.


### OAuth scopes

| UI Name | Permission | Parameter |
|:--------|:-----------|:----------|
|  Products | modify | `store_v2_products` |
|  Products | read-only | `store_v2_products_read_only` |

### Authentication header

| Header | Argument | Description |
|:-------|:---------|:------------|
| `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |

### Further reading

For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).

For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).

For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).

X-Auth-Token

BigCommerce

The Catalog API manages shared options and shared modifiers. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog).    

To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. 

Catalog - Shared Options and Modifiers

Delete shared modifiers by modifier ID, for example, `?id:in=1,2,3`.

id:in

An array of shared modifiers and metadata

Modifier was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

Bulk update shared modifiers using modifier IDs.

The ID of the `Shared Modifier` to which the resource belongs.

modifier_id

Delete modifier values for a shared modifier. Use value IDs in the query parameter, for example, `?id:in=1,2,3`.

Get modifier values for a shared modifier.

An array of shared modifier values and metadata.

Bulk create modifier values for a shared modifier.

An array of `SharedModifierValue` objects.

Modifier value was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

Bulk update modifier values for a shared modifier, using value IDs.

Get a modifier value for a shared modifier by using a value ID and modifier ID.

The ID of the `Shared Modifier Value` to which the resource belongs.

Delete shared options by ID, for example, `?id:in=1,2,3`.

An array of `SharedProductOption` objects.

Option was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

Bulk update shared options using option IDs.

The ID of the `Shared Option` to which the resource belongs.

option_id

Delete option values for a shared option. Use value IDs in the query parameter, for example, `?id:in=1,2,3`.

Bulk create option values for an existing shared option.

An array of `SharedProductOptionValue` objects.

Option value was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.

Bulk update option values for an existing shared option, using value IDs.

An array of `SharedProductOptionValue` objects.    

Get an option value for a shared option by using a value ID and option ID.

The ID of the `Shared Option Value` to which the resource belongs.

Options

Get Shared Options

Create Shared Options (Batch)

Update Shared Options (Batch)

Delete Shared Options

Get a Shared Option