openapi: 3.0.0 info: title: BigCommerce Abandoned Cart Emails Metafields API version: 3.0.0 termsOfService: https://www.bigcommerce.com/terms description: Abandoned Cart Emails V3 API managing Handlebars-based emails. contact: name: BigCommerce url: https://www.bigcommerce.com email: support@bigcommerce.com servers: - url: https://api.bigcommerce.com/stores/{store_hash}/v3 variables: store_hash: default: store_hash description: Permanent ID of the BigCommerce store. description: BigCommerce API Gateway security: - X-Auth-Token: [] tags: - name: Metafields paths: /carts/{cart_id}/metafields: parameters: - $ref: '#/components/parameters/cart_id' - $ref: '#/components/parameters/Accept' get: summary: BigCommerce Get Cart Metafields tags: - Metafields description: Get a cart's metafields. operationId: getCartMetafields parameters: - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/MetafieldKeyParam' - $ref: '#/components/parameters/MetafieldNamespaceParam' - $ref: '#/components/parameters/DirectionParam' responses: '200': description: 'An array of metafields and metadata. ' content: application/json: schema: $ref: '#/components/schemas/MetafieldResponse' '409': description: 'The `Metafield` conflicts with another `Metafield`. This can result from duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'The `Metafield` is not valid. This is the result of missing required fields or of invalid data. See the response for more details. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: BigCommerce Create a Cart Metafield tags: - Metafields description: "Create a cart `Metafield`. \n\nIf you create an order from a Cart, you can continue referencing the Cart Metafields even if you delete the original Cart. Use the `cart_id` field on the Order to construct the Cart Metafield endpoint. \n" operationId: createCartMetafield parameters: - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: schema: $ref: '#/components/schemas/MetafieldBase_Post' example: permission_set: app_only namespace: Sales Department key: Staff Name value: Sam description: Name of staff member description: '' required: true responses: '200': description: 'A `Metafield` object. ' content: application/json: schema: $ref: '#/components/schemas/MetaFieldCollectionResponse' example: data: id: '24' key: Staff Name value: Sam namespace: Sales Department permission_set: app_only resource_type: cart resource_id: b810114d-9926-45b7-bba5-7633b251154b description: Name of staff member date_created: 2023-11-15 15:16:35+00:00 date_modified: 2023-11-15 15:16:35+00:00 meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: example-1: value: status: 404 title: There was no order found with ID 1010 type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes /carts/{cart_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/cart_id' - schema: type: integer name: metafield_id in: path required: true description: The unique ID of the subject `Metafield`. get: summary: BigCommerce Get a Cart Metafield tags: - Metafields description: Gets a cart metafield. operationId: getCartMetafield responses: '200': description: 'A `Metafield` object. ' content: application/json: schema: $ref: '#/components/schemas/MetafieldResponse' '409': description: 'The `Metafield` conflicts with another `Metafield`. This can result from duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'The `Metafield` is not valid. This is the result of missing required fields or of invalid data. See the response for more details. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error parameters: - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/MetafieldKeyParam' - $ref: '#/components/parameters/MetafieldNamespaceParam' - $ref: '#/components/parameters/DirectionParam' put: summary: BigCommerce Update a Cart Metafield tags: - Metafields description: 'Update a `Metafield`, by `cart_id`. ' operationId: updateCartMetafield parameters: - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: schema: $ref: '#/components/schemas/MetafieldBase_Post' examples: {} description: 'A `Metafield` object. ' required: true responses: '200': description: 'A metafield and metadata. ' content: application/json: schema: $ref: '#/components/schemas/MetaFieldCollectionResponse' examples: {} '404': description: 'The resource was not found. ' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: example-1: value: status: 404 title: There was no order found with ID 1010 type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes delete: summary: BigCommerce Delete a Metafield tags: - Metafields description: 'Deletes a `Metafield`. ' operationId: deleteCartMetafield responses: '204': description: "An empty response. \n" /catalog/brands/{brand_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/BrandIdParam' get: tags: - Metafields summary: BigCommerce Get Brand Metafields description: 'Returns a list of *Brand Metafields*. Optional filter parameters can be passed in. ' operationId: getBrandMetafields parameters: - name: id in: query description: 'Filter items by ID. ' schema: type: integer - name: id:in in: query style: form explode: false schema: type: array items: type: integer - name: id:not_in in: query style: form explode: false schema: type: array items: type: integer - name: id:min in: query style: form explode: false schema: type: array items: type: integer - name: id:max in: query style: form explode: false schema: type: array items: type: integer - name: id:greater in: query style: form explode: false schema: type: array items: type: integer - name: id:less in: query style: form explode: false schema: type: array items: type: integer - name: page in: query description: Specifies the page number in a limited (paginated) list of products. schema: type: integer - name: limit in: query description: Controls the number of items per page in a limited (paginated) list of products. schema: type: integer - name: key in: query description: 'Filter based on a metafieldʼs key. ' schema: type: string - name: namespace in: query description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Meta Field Collection Response type: object properties: data: type: array items: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaCollection_Full' example: data: - id: 6 key: Location value: 4HG namespace: Warehouse Locations permission_set: app_only resource_type: brand resource_id: 111 description: Location in the warehouse date_created: '1973-01-20T21:34:57.903Z' date_modified: '1990-12-30T00:29:23.515Z' - id: 7 key: Brand location value: 4HG namespace: Warehouse Locations permission_set: read resource_type: brand resource_id: 111 description: Location in the warehouse date_created: '1973-01-20T21:34:57.903Z' date_modified: '1990-12-30T00:29:23.515Z' meta: pagination: total: 2 count: 2 per_page: 50 current_page: 1 total_pages: 1 links: current: ?page=1&limit=50 '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. post: tags: - Metafields summary: BigCommerce Create a Brand Metafield description: 'Creates a *Brand Metafield*. **Required Fields** - permission_set - namespace - key - value **Read-Only Fields** - id **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' operationId: createBrandMetafield parameters: - $ref: '#/components/parameters/ContentType_2' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Base' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: title: Meta type: object properties: {} description: Empty meta object; may be used later. examples: example-1: value: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: brand resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} example-2: value: data: id: 6 key: Location value: 4HG namespace: Warehouse Locations permission_set: app_only resource_type: category resource_id: 111 description: Location in the warehouse. date_created: '2018-05-07T20:14:17+00:00' date_modified: '2018-05-07T20:14:17+00:00' meta: {} example-3: value: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: brand resource_id: 137 description: Where products are located. date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '409': description: 'The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combination of the appʼs client id, namespace, key, resource_type, and resource_id. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: 'The HTTP status code. ' title: type: string description: 'The error title describing the particular error. ' type: type: string '422': description: 'The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: 'The HTTP status code. ' title: type: string description: 'The error title describing the particular error. ' type: type: string x-codegen-request-body-name: Metafield /catalog/brands/{brand_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/BrandIdParam' - $ref: '#/components/parameters/MetafieldIdParam' get: tags: - Metafields summary: BigCommerce Get a Brand Metafields description: Returns a *Brand Metafield*. Optional filter parameters can be passed in. operationId: getBrandMetafield parameters: - name: metafield_id in: path description: 'The ID of the `Metafield`. ' required: true schema: type: integer - name: brand_id in: path description: 'The ID of the `Brand` to which the resource belongs. ' required: true schema: type: integer - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: product resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. put: tags: - Metafields summary: BigCommerce Update a Brand Metafield description: "Updates a *Brand Metafield*.\n\n**Required Fields** \n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message.\n* The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center." operationId: updateBrandMetafield parameters: - name: metafield_id in: path description: 'The ID of the `Metafield`. ' required: true schema: type: integer - name: brand_id in: path description: 'The ID of the `Brand` to which the resource belongs. ' required: true schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/MetafieldBase_Put' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: product resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. x-codegen-request-body-name: Metafield delete: tags: - Metafields summary: BigCommerce Delete a Brand Metafield description: Deletes a *Brand Metafield*. operationId: deleteBrandMetafield parameters: - name: metafield_id in: path description: 'The ID of the `Metafield`. ' required: true schema: type: integer - name: brand_id in: path description: 'The ID of the `Brand` to which the resource belongs. ' required: true schema: type: integer responses: '204': description: '' content: {} /catalog/categories/{category_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/CategoryIdParam' get: tags: - Metafields summary: BigCommerce Get Category Metafields description: Returns a list of *Metafields* on a *Category*. Optional filter parameters can be passed in. operationId: getCategoryMetafields parameters: - name: id in: query description: 'Filter items by ID. ' schema: type: integer - name: id:in in: query style: form explode: false schema: type: array items: type: integer - name: id:not_in in: query style: form explode: false schema: type: array items: type: integer - name: id:min in: query style: form explode: false schema: type: array items: type: integer - name: id:max in: query style: form explode: false schema: type: array items: type: integer - name: id:greater in: query style: form explode: false schema: type: array items: type: integer - name: id:less in: query style: form explode: false schema: type: array items: type: integer - name: page in: query description: Specifies the page number in a limited (paginated) list of products. schema: type: integer - name: limit in: query description: Controls the number of items per page in a limited (paginated) list of products. schema: type: integer - name: key in: query description: 'Filter based on a metafieldʼs key. ' schema: type: string - name: namespace in: query description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Meta Field Collection Response type: object properties: data: type: array items: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaCollection_Full' example: data: - id: 6 key: Location value: 4HG namespace: Warehouse Locations permission_set: app_only resource_type: category resource_id: 111 description: Location in the warehouse date_created: '1973-01-20T21:34:57.903Z' date_modified: '1990-12-30T00:29:23.515Z' - id: 7 key: Location value: 4HG namespace: Warehouse Locations permission_set: read resource_type: category resource_id: 111 description: Location in the warehouse date_created: '1973-01-20T21:34:57.903Z' date_modified: '1990-12-30T00:29:23.515Z' meta: pagination: total: 2 count: 2 per_page: 50 current_page: 1 total_pages: 1 links: current: ?page=1&limit=50 '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. post: tags: - Metafields summary: BigCommerce Create a Category Metafield description: 'Creates a *Category Metafield*. **Required Fields:** - permission_set - namespace - key - value **Read-Only Fields** - id **Note:** The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' operationId: createCategoryMetafield parameters: - $ref: '#/components/parameters/ContentType_3' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Base_2' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: category resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '409': description: 'The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate, unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: 'The HTTP status code. ' title: type: string description: 'The error title describing the particular error. ' type: type: string '422': description: 'The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: 'The HTTP status code. ' title: type: string description: 'The error title describing the particular error. ' type: type: string x-codegen-request-body-name: Metafield /catalog/categories/{category_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/CategoryIdParam' - $ref: '#/components/parameters/MetafieldIdParam' get: tags: - Metafields summary: BigCommerce Get a Category Metafield description: Returns a single *Category Metafield*. Optional parameters can be passed in. operationId: getCategoryMetafield parameters: - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: category resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '404': description: The resource was not found. content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. put: tags: - Metafields summary: BigCommerce Update a Category Metafield description: "Updates a *Category Metafield*.\n\n**Required Fields**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. " operationId: updateCategoryMetafield parameters: - $ref: '#/components/parameters/ContentType_3' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Base_2' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: category resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. x-codegen-request-body-name: Metafield delete: tags: - Metafields summary: BigCommerce Delete a Category Metafield description: Deletes a *Category Metafield*. operationId: deleteCategoryMetafield responses: '204': description: '' content: {} /catalog/products/{product_id}/variants/{variant_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ProductIdParam' - $ref: '#/components/parameters/VariantIdParam' get: tags: - Metafields summary: BigCommerce Get Product Variant Metafields description: Returns a list of product variant *Metafields*. Optional parameters can be passed in. operationId: getProductVariantMetafields parameters: - name: variant_id in: path description: 'ID of the variant on a product, or on an associated Price List Record. ' required: true schema: type: integer - name: page in: query description: Specifies the page number in a limited (paginated) list of products. schema: type: integer - name: limit in: query description: Controls the number of items per page in a limited (paginated) list of products. schema: type: integer - name: key in: query description: 'Filter based on a metafieldʼs key. ' schema: type: string - name: namespace in: query description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Meta Field Collection Response type: object properties: data: type: array items: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/categoriesTree_Resp' '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. post: tags: - Metafields summary: BigCommerce Create a Product Variant Metafield description: 'Creates a product variant *Metafield*. **Required Fields:** * permission_set * namespace * key * value **Read-Only Fields** * id **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' operationId: createProductVariantMetafield parameters: - $ref: '#/components/parameters/ContentType_4' - name: variant_id in: path description: 'ID of the variant on a product, or on an associated Price List Record. ' required: true schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Base_3' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: variant resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '409': description: 'The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique-key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: 'The HTTP status code. ' title: type: string description: 'The error title describing the particular error. ' type: type: string '422': description: 'The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: 'The HTTP status code. ' title: type: string description: 'The error title describing the particular error. ' type: type: string x-codegen-request-body-name: Metafield /catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ProductIdParam' - $ref: '#/components/parameters/VariantIdParam' - $ref: '#/components/parameters/MetafieldIdParam' get: tags: - Metafields summary: BigCommerce Get a Product Variant Metafields description: Returns a single product variant *Metafield*. Optional parameters can be passed in. operationId: getProductVariantMetafield parameters: - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 8 key: location_id value: Shelf 3, Bin 5 namespace: Inventory Namespace permission_set: read resource_type: variant resource_id: 158 description: Where products are located date_created: '2018-09-13T16:42:37+00:00' date_modified: '2018-09-13T16:42:37+00:00' meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. put: tags: - Metafields summary: BigCommerce Update Product Variant Metafields description: "Updates a product variant *Metafield*.\n\n**Required Fields:**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. " operationId: updateProductVariantMetafield parameters: - $ref: '#/components/parameters/ContentType_4' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Base_3' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 8 key: location_id value: Shelf 3, Bin 5 namespace: Inventory Namespace permission_set: read resource_type: variant resource_id: 158 description: Where products are located date_created: '2018-09-13T16:42:37+00:00' date_modified: '2018-09-13T16:42:37+00:00' meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. x-codegen-request-body-name: Metafield delete: tags: - Metafields summary: BigCommerce Delete a Product Variant Metafield description: Deletes a product variant *Metafield*. operationId: deleteProductVariantMetafield responses: '204': description: '' content: {} /catalog/products/{product_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ProductIdParam_2' get: tags: - Metafields summary: BigCommerce Get Product Metafields description: Returns a list of *Product Metafields*. Optional parameters can be passed in. operationId: getProductMetafields parameters: - name: page in: query description: Specifies the page number in a limited (paginated) list of products. schema: type: integer - name: limit in: query description: Controls the number of items per page in a limited (paginated) list of products. schema: type: integer - name: key in: query description: 'Filter based on a metafieldʼs key. ' schema: type: string - name: namespace in: query description: Filter based on a metafieldʼs namespace. schema: type: string - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Meta Field Collection Response type: object properties: data: type: array items: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaCollection_Full' example: data: - id: 6 key: Location value: 4HG namespace: Warehouse Locations permission_set: app_only resource_type: product resource_id: 111 description: Location in the warehouse date_created: '1973-01-20T21:34:57.903Z' date_modified: '1990-12-30T00:29:23.515Z' - id: 7 key: Sublocation value: 4HG namespace: Warehouse Locations permission_set: read resource_type: product resource_id: 111 description: Location in the warehouse date_created: '1973-01-20T21:34:57.903Z' date_modified: '1990-12-30T00:29:23.515Z' meta: pagination: total: 2 count: 2 per_page: 50 current_page: 1 total_pages: 1 links: current: ?page=1&limit=50 '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. post: tags: - Metafields summary: BigCommerce Create a Product Metafield description: 'Creates a *Product Metafield*. **Required Fields:** * permission_set * namespace * key * value **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' operationId: createProductMetafield parameters: - $ref: '#/components/parameters/ContentType_5' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Base_4' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 8 key: location_id value: Shelf 3, Bin 5 namespace: Inventory Namespace permission_set: read resource_type: product resource_id: 158 description: Where products are located date_created: '2018-09-13T16:42:37+00:00' date_modified: '2018-09-13T16:42:37+00:00' meta: {} '409': description: 'The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combinations of the appʼs client ID, namespace, key, resource_type, and resource_id. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: The HTTP status code. title: type: string description: The error title describing the particular error. type: type: string '422': description: 'The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. ' content: application/json: schema: title: Error Response type: object properties: errors: title: Detailed Errors type: object properties: {} additionalProperties: true instance: type: string status: type: integer description: 'The HTTP status code. ' title: type: string description: 'The error title describing the particular error. ' type: type: string /catalog/products/{product_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ProductIdParam_2' - $ref: '#/components/parameters/MetafieldIdParam' get: tags: - Metafields summary: BigCommerce Get a Product Metafield description: Returns a single *Product Metafield*. Optional parameters can be passed in. operationId: getProductMetafield parameters: - name: include_fields in: query description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. schema: type: string - name: exclude_fields in: query description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. schema: type: string responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: product resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. put: tags: - Metafields summary: BigCommerce Update a Product Metafield description: "Updates a *Product Metafield*.\n\n**Required Fields**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified using the API account that created the metafield:\n\t* `namespace`\n\t* `key`\n\t* `permission_set`\n\t* `value`\n\n**Usage Notes**\n* Attempting to modify the `namespace`, `key`, `permission_set`, or `value` field using an API account different from the one used to create those metafields will result in a `403` error message. " operationId: updateProductMetafield parameters: - $ref: '#/components/parameters/ContentType_5' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Base_4' required: true responses: '200': description: '' content: application/json: schema: title: Metafield Response type: object properties: data: $ref: '#/components/schemas/metafield_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' example: data: id: 4 key: location_id value: Shelf 3, Bin 5 namespace: App Namespace permission_set: app_only resource_type: product resource_id: 137 description: Where products are located date_created: '2021-08-06T19:15:35+00:00' date_modified: '2021-08-06T19:15:35+00:00' meta: {} '404': description: 'The resource was not found. ' content: application/json: schema: title: Not Found type: object properties: status: type: integer description: '404 HTTP status code. ' title: type: string description: The error title describing the particular error. type: type: string instance: type: string description: Error payload for the BigCommerce API. x-codegen-request-body-name: Metafield delete: tags: - Metafields summary: BigCommerce Delete a Product Metafield description: Deletes a *Product Metafield*. operationId: deleteProductMetafield responses: '204': description: '' content: {} /channels/{channel_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/channel_id_path_param' get: summary: BigCommerce Get Channel Metafields tags: - Metafields responses: '200': $ref: '#/components/responses/metafield_200' operationId: getChannelMetafields parameters: - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/MetafieldKeyParam_2' - $ref: '#/components/parameters/MetafieldNamespaceParam_2' - $ref: '#/components/parameters/DirectionParam_2' description: Returns a list of metafields on a channel. Optional filter parameters can be passed in. post: summary: BigCommerce Create a Channel Metafield parameters: - $ref: '#/components/parameters/ContentType_6' operationId: createChannelMetafield responses: '200': $ref: '#/components/responses/metafield_200' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Post' examples: {} tags: - Metafields description: 'Creates a channel metafield. **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, channel, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' /channels/{channel_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/channel_id_path_param' - name: metafield_id schema: type: string in: path required: true get: summary: BigCommerce Get a Channel Metafield tags: - Metafields responses: '200': $ref: '#/components/responses/metafield_200' operationId: getChannelMetafield description: Returns a single channel metafield. put: summary: BigCommerce Update a Channel Metafield parameters: - $ref: '#/components/parameters/ContentType_6' operationId: updateChannelMetafield responses: '200': $ref: '#/components/responses/metafield_200' requestBody: content: application/json: schema: $ref: '#/components/schemas/metafield_Put' tags: - Metafields description: 'Updates a single channel metafield. **Usage Notes** * Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a `403` error message. ' delete: summary: BigCommerce Delete a Channel Metafield operationId: deleteChannelMetafield responses: '204': description: No Content tags: - Metafields description: Deletes a single channel metafield. /orders/{order_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/OrderIdParam' get: summary: BigCommerce Get Order Metafields tags: - Metafields description: 'Gets a `Metafield` object list, by `order_id`. The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. ' operationId: getOrderMetafields parameters: - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/MetafieldKeyParam_3' - $ref: '#/components/parameters/MetafieldNamespaceParam_3' - $ref: '#/components/parameters/DirectionParam' responses: '200': description: 'An array of metafields and metadata. ' content: application/json: schema: $ref: '#/components/schemas/MetaFieldCollectionResponse_2' examples: {} '404': description: 'The resource was not found. ' content: application/json: schema: $ref: '#/components/schemas/NotFound' examples: example-1: value: status: 404 title: There was no order found with ID 1010 type: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes post: summary: BigCommerce Create Metafields tags: - Metafields description: 'Creates an order `Metafield`. The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID.' operationId: createOrderMetafield parameters: - $ref: '#/components/parameters/ContentType_7' requestBody: content: application/json: schema: $ref: '#/components/schemas/MetafieldBase_Post_2' examples: {} description: 'A `Metafield` object. ' required: true responses: '200': description: 'A `Metafield` object. ' content: application/json: schema: $ref: '#/components/schemas/MetafieldResponse_2' '409': description: 'The `Metafield` conflicts with another `Metafield`. This can result from duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse_2' '422': description: 'The `Metafield` is not valid. This is the result of missing required fields or of invalid data. See the response for more details. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse_2' /orders/{order_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/OrderIdParam' - name: metafield_id in: path description: 'The ID of the `Metafield`. ' required: true schema: type: integer get: summary: BigCommerce Get a Metafield tags: - Metafields description: 'Gets a `Metafield`, by `order_id`. ' operationId: getOrderMetafield responses: '200': description: 'A `Metafield` object. ' content: application/json: schema: $ref: '#/components/schemas/MetafieldResponse_2' '404': description: 'The resource was not found. ' content: application/json: schema: $ref: '#/components/schemas/NotFound' put: summary: BigCommerce Update a Metafield tags: - Metafields description: 'Updates a `Metafield` object. The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID.' operationId: updateOrderMetafield parameters: - $ref: '#/components/parameters/ContentType_7' requestBody: content: application/json: schema: $ref: '#/components/schemas/MetafieldPut' description: 'A `Metafield` object. ' required: true responses: '200': description: 'A metafield and metadata. ' content: application/json: schema: $ref: '#/components/schemas/MetafieldResponse_2' '404': description: 'The resource was not found. ' content: application/json: schema: $ref: '#/components/schemas/NotFound' delete: summary: BigCommerce Delete a Metafield tags: - Metafields description: 'Deletes a `Metafield`. ' operationId: deleteOrderMetafield responses: '204': description: 'An empty response. ' components: parameters: MetafieldNamespaceParam_2: name: namespace in: query description: Filter based on a metafieldʼs namespace. required: false schema: type: string MetafieldIdParam: name: metafield_id in: path description: 'The ID of the `Metafield`. ' required: true schema: type: integer OrderIdParam: name: order_id in: path description: 'The ID of the `Order` to which the transactions belong. ' required: true schema: type: integer MetafieldNamespaceParam_3: name: namespace in: query description: 'Filter based on a metafieldʼs key. ' required: false schema: type: string ContentType_5: name: Content-Type in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json MetafieldKeyParam_2: name: key in: query description: 'Filter based on a metafieldʼs key. ' required: false schema: type: string MetafieldNamespaceParam: name: namespace in: query description: Filter based on a metafieldʼs namespaces. required: false schema: type: string DirectionParam: name: direction description: 'Sort direction. Acceptable values are: `asc`, `desc`. ' required: false in: query schema: type: string enum: - asc - desc Accept: name: Accept in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. schema: type: string default: application/json DirectionParam_2: name: direction description: 'Sort direction. Acceptable values are: `asc`, `desc`.' required: false in: query schema: type: string enum: - asc - desc cart_id: name: cart_id in: path description: The ID of the `Cart` to which the transactions belong. required: true schema: type: string format: UUID ProductIdParam: name: product_id in: path description: 'The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the `product_id` in the request path are successful as long as the parameter is not empty. The `product_id` segment is there only for path consistency. ' required: true schema: type: integer ContentType_7: name: Content-Type in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json ContentType_3: name: Content-Type in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json ContentType_2: name: Content-Type in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json MetafieldKeyParam: name: key in: query description: Filter based on a metafieldʼs key. required: false schema: type: string ContentType_4: name: Content-Type in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json ContentType_6: name: Content-Type in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json CategoryIdParam: name: category_id in: path description: 'The ID of the `Category` to which the resource belongs. ' required: true schema: type: integer ProductIdParam_2: name: product_id in: path description: 'The ID of the `Product` to which the resource belongs. ' required: true schema: type: integer PageParam: name: page description: 'Specifies the page number in a limited (paginated) list of products. ' required: false in: query schema: type: integer BrandIdParam: name: brand_id in: path description: 'The ID of the `Brand` to which the resource belongs. ' required: true schema: type: integer LimitParam: name: limit description: 'Controls the number of items per page in a limited (paginated) list of products. ' required: false in: query schema: type: integer ContentType: name: Content-Type in: header required: true schema: type: string default: application/json VariantIdParam: name: variant_id in: path description: 'ID of the variant on a product, or on an associated Price List Record. ' required: true schema: type: integer channel_id_path_param: name: channel_id description: The ID of a channel. in: path required: true schema: type: integer format: int64 MetafieldKeyParam_3: name: key in: query description: 'Filter based on a metafieldʼs key. ' required: false schema: type: string responses: metafield_200: description: OK content: application/json: schema: description: Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. x-internal: false type: object properties: id: type: integer description: Unique ID of the *Metafield*. example: 6 permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description |-|-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: maxLength: 64 minLength: 1 type: string description: Namespace for the metafield, for organizational purposes. example: Warehouse Locations x-required: - post key: maxLength: 64 minLength: 1 type: string description: "The name of the field, for example: `location_id`, `color`. \n" example: Location x-required: - post value: maxLength: 65535 minLength: 1 type: string description: 'The value of the field. ' example: 4HG x-required: - post description: maxLength: 255 minLength: 0 type: string description: 'Description for the metafields. ' example: Location in the warehouse resource_type: type: string description: 'The type of resource with which the metafield is associated. ' example: product enum: - category - brand - product - variant x-required: - post resource_id: maximum: 10000000000 minimum: 0 type: integer description: 'The ID for the resource with which the metafield is associated. ' example: 111 x-required: - post date_created: type: string description: 'Date and time of the metafieldʼs creation. Read-Only. ' format: date-time example: '2018-05-07T20:14:17.000Z' date_modified: type: string description: 'Date and time when the metafield was last updated. Read-Only. ' format: date-time example: '2018-05-07T20:14:17.000Z' schemas: metaEmpty_Full: type: object title: Response meta properties: {} additionalProperties: true description: Response metadata. CollectionMeta_2: type: object description: Data about the response, including pagination and collection totals. properties: pagination: type: object description: Data about the response, including pagination and collection totals. title: Pagination properties: total: type: integer description: 'Total number of items in the result set. ' example: 36 count: type: integer description: 'Total number of items in the collection response. ' example: 36 per_page: type: integer description: 'The amount of items returned in the collection per page, controlled by the limit parameter. ' example: 50 current_page: type: integer description: 'The page you are currently on within the collection. ' example: 1 total_pages: type: integer description: 'The total number of pages in the collection. ' example: 1 links: type: object description: 'Pagination links for the previous and next parts of the whole collection. ' properties: previous: type: string description: 'Link to the previous page returned in the response. ' current: type: string description: 'Link to the current page returned in the response. ' example: ?page=1&limit=50 next: type: string description: 'Link to the next page returned in the response. ' title: Collection Meta x-internal: false Meta: type: object title: Meta properties: meta: type: object description: Data about the response, including pagination and collection totals. title: Pagination properties: total: type: integer description: 'Total number of items in the result set. ' example: 36 count: type: integer description: 'Total number of items in the collection response. ' example: 36 per_page: type: integer description: 'The amount of items returned in the collection per page, controlled by the limit parameter. ' example: 50 current_page: type: integer description: 'The page you are currently on within the collection. ' example: 1 total_pages: type: integer description: 'The total number of pages in the collection. ' example: 1 links: type: object description: 'Pagination links for the previous and next parts of the whole collection. ' properties: previous: type: string description: 'Link to the previous page returned in the response. ' current: type: string description: 'Link to the current page returned in the response. ' example: ?page=1&limit=50 next: type: string description: 'Link to the next page returned in the response. ' x-internal: false ErrorResponse: type: object properties: status: type: integer title: type: string type: type: string instance: type: string errors: type: object x-tags: - Models MetaFieldCollectionResponse_2: type: object description: 'Response payload for the BigCommerce API. ' properties: data: type: array items: $ref: '#/components/schemas/Metafield_2' meta: $ref: '#/components/schemas/CollectionMeta_2' x-internal: false metafield_Post: title: metafield_Post type: object description: Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. x-internal: false properties: namespace: maxLength: 64 minLength: 1 type: string description: Namespace for the metafield, for organizational purposes. This is set by the developer. example: Warehouse Locations x-required: - post key: maxLength: 64 minLength: 1 type: string description: 'The name of the field. ' example: Location x-required: - post value: maxLength: 65535 minLength: 1 type: string description: 'The value of the field. ' example: 4HG x-required: - post permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description |-|-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access description: maxLength: 255 minLength: 0 type: string description: 'Description for the metafield. ' example: Location in the warehouse required: - namespace - key - value - permission_set pagination_Full: title: pagination_Full type: object properties: total: type: integer description: 'Total number of items in the result set. ' example: 36 count: type: integer description: 'Total number of items in the collection response. ' example: 36 per_page: type: integer description: 'The amount of items returned in the collection per page, controlled by the limit parameter. ' example: 50 current_page: type: integer description: 'The page you are currently on within the collection. ' example: 1 total_pages: type: integer description: 'The total number of pages in the collection. ' example: 1 links: type: object properties: previous: type: string description: 'Link to the previous page returned in the response. ' current: type: string description: 'Link to the current page returned in the response. ' example: ?page=1&limit=50 next: type: string description: 'Link to the next page returned in the response. ' description: 'Pagination links for the previous and next parts of the whole collection. ' description: Data about the response, including pagination and collection totals. x-internal: false Metafield: description: 'Allows app partners to write custom data to various resources in the API. ' allOf: - $ref: '#/components/schemas/MetafieldBase' - type: object properties: id: type: string description: The unique identifier for the metafield. date_created: type: string format: date-time description: Date and time of the metafieldʼs creation. example: '2022-06-16T18:39:00+00:00' date_modified: type: string format: date-time description: Date and time when the metafield was last updated. example: '2022-06-16T18:39:00+00:00' owner_client_id: type: string description: Client ID for the metafieldʼs creator. example: asdfasdfasdfasdfasdfasdfasdf readOnly: true x-internal: false MetafieldBase_Put: type: object description: 'Common Metafield properties. ' x-internal: false properties: permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. | Value | Description | | : | : | | `app_only` | Private to the app that owns the field. | | `read` | Visible to other API consumers. | | `write` | Open for reading and writing by other API consumers. | | `read_and_sf_access` | Visible to other API consumers, including on the storefront. | | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. | ' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: type: string description: 'Namespace for the metafield, for organizational purposes. ' example: Sales Department minLength: 1 maxLength: 64 key: type: string description: 'The name of the field, for example: `location_id`, `color`. ' minLength: 1 maxLength: 64 example: Staff Name value: type: string description: 'The value of the field, for example: `1`, `blue`. ' minLength: 1 maxLength: 65535 example: Ronaldo description: type: string description: 'Description for the metafields. ' minLength: 0 maxLength: 255 example: Name of Staff Member metaCollection_Full: title: metaCollection_Full type: object properties: pagination: $ref: '#/components/schemas/pagination_Full' description: Data about the response, including pagination and collection totals. x-internal: false ErrorResponse_2: allOf: - $ref: '#/components/schemas/error_Base' - type: object properties: errors: type: object properties: {} additionalProperties: true title: DetailedErrors title: ErrorResponse x-internal: false MetafieldBase_2: type: object description: 'Common Metafield properties. ' x-internal: false properties: permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description | |:-|:-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| ' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: type: string description: 'Namespace for the metafield, for organizational purposes. ' example: Sales Department minLength: 1 maxLength: 64 key: type: string description: 'The name of the field, for example: `location_id`, `color`. ' minLength: 1 maxLength: 64 example: Staff Name value: type: string description: 'The value of the field, for example: `1`, `blue`. ' minLength: 1 maxLength: 65535 example: Ronaldo description: type: string description: 'Description for the metafields. ' example: order minLength: 0 maxLength: 255 resource_type: type: string description: 'The type of resource with which the metafield is associated. ' enum: - order - brand - product - variant - category example: order resource_id: type: integer description: 'The unique identifier for the resource with which the metafield is associated. ' example: 0 readOnly: true required: - permission_set MetafieldBase: type: object description: 'Common Metafield properties. ' x-internal: false properties: permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. | Value | Description | | : | : | | `app_only` | Private to the app that owns the field. | | `read` | Visible to other API consumers. | | `write` | Open for reading and writing by other API consumers. | | `read_and_sf_access` | Visible to other API consumers, including on the storefront. | | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. | ' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: type: string description: 'Namespace for the metafield, for organizational purposes. ' example: Sales Department minLength: 1 maxLength: 64 key: type: string description: 'The name of the field, for example: `location_id`, `color`. ' minLength: 1 maxLength: 64 example: Staff Name value: type: string description: 'The value of the field, for example: `1`, `blue`. ' minLength: 1 maxLength: 65535 example: Ronaldo description: type: string description: 'Description for the metafields. ' example: order minLength: 0 maxLength: 255 resource_type: type: string description: 'The type of resource with which the metafield is associated. ' enum: - brand - product - variant - category - cart example: cart resource_id: type: string description: 'The unique identifier for the resource with which the metafield is associated. ' example: '0' readOnly: true required: - permission_set metafield_Put: title: metafield_Put type: object description: Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. x-internal: false properties: namespace: maxLength: 64 minLength: 1 type: string description: Namespace for the metafield, for organizational purposes. example: Warehouse Locations x-required: - post key: maxLength: 64 minLength: 1 type: string description: 'The name of the field. ' example: Location x-required: - post value: maxLength: 65535 minLength: 1 type: string description: 'The value of the field. ' example: 4HG x-required: - post permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description |-|-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access description: maxLength: 255 minLength: 0 type: string description: 'Description for the metafield. ' example: Location in the warehouse. CollectionMeta: type: object description: Data about the response, including pagination and collection totals. properties: pagination: type: object description: Data about the response, including pagination and collection totals. title: Pagination properties: total: type: integer description: 'Total number of items in the result set. ' example: 36 count: type: integer description: 'Total number of items in the collection response. ' example: 36 per_page: type: integer description: 'The amount of items returned in the collection per page, controlled by the limit parameter. ' example: 50 current_page: type: integer description: 'The page you are currently on within the collection. ' example: 1 total_pages: type: integer description: 'The total number of pages in the collection. ' example: 1 links: type: object description: 'Pagination links for the previous and next parts of the whole collection. ' properties: previous: type: string description: 'Link to the previous page returned in the response. ' current: type: string description: 'Link to the current page returned in the response. ' example: ?page=1&limit=50 next: type: string description: 'Link to the next page returned in the response. ' additionalProperties: true title: Collection Meta x-internal: false metafield_Base_3: title: metafield_Base type: object description: Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. x-internal: false properties: key: maxLength: 64 minLength: 1 type: string description: 'The name of the field, for example: `location_id`, `color`. Required for POST. ' example: Location x-required: - post value: maxLength: 65535 minLength: 1 type: string description: 'The value of the field, for example: `1`, `blue`. Required for POST. ' example: 4HG x-required: - post namespace: maxLength: 64 minLength: 1 type: string description: 'Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. ' example: Warehouse Locations x-required: - post permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description |-|-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access description: maxLength: 255 minLength: 1 type: string description: 'Description for the metafields. ' example: Location in the warehouse required: - permission_set - namespace - key - value Metafield_2: description: 'Allows app partners to write custom data to various resources in the API. ' allOf: - $ref: '#/components/schemas/MetafieldBase_2' - type: object properties: id: type: integer description: 'The unique identifier for the metafields. ' date_created: type: string format: date-time description: 'Date and time of the metafieldʼs creation. ' example: '2022-06-16T18:39:00+00:00' date_modified: type: string format: date-time description: 'Date and time when the metafield was last updated. ' example: '2022-06-16T18:39:00+00:00' owner_client_id: type: string description: Client ID for the metafieldʼs creator. example: asdfasdfasdfasdfasdfasdfasdf readOnly: true x-internal: false x-examples: {} categoriesTreeNode_Full: title: categoriesTreeNode_Full type: object properties: id: type: integer description: 'The unique numeric ID of the category; increments sequentially. ' example: 26 parent_id: type: integer description: 'The unique numeric ID of the categoryʼs parent. This field controls where the category sits in the tree of categories that organize the catalog. ' example: 25 name: type: string description: 'The name displayed for the category. Name is unique with respect to the categoryʼs siblings. ' example: Bath is_visible: type: boolean description: 'Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. ' example: true url: type: string description: 'The custom URL for the category on the storefront. ' example: /towels/bath-towels/ description: Used to reflect parent <> child category relationships. Used by Category Tree. x-internal: false metafield_Base_4: title: metafield_Base type: object description: Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. x-internal: false properties: key: maxLength: 64 minLength: 1 type: string description: 'The name of the field, for example: `location_id`, `color`. Required for POST. ' example: Location x-required: - post value: maxLength: 65535 minLength: 1 type: string description: 'The value of the field, for example: `1`, `blue`. Required for POST. ' example: 4HG x-required: - post namespace: maxLength: 64 minLength: 1 type: string description: 'Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. ' example: Warehouse Locations x-required: - post permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description |-|-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access description: maxLength: 255 minLength: 0 type: string description: 'Description for the metafields. ' example: Location in the warehouse required: - permission_set - namespace - key - value MetafieldBase_Post: type: object description: 'Common Metafield properties. ' x-internal: false properties: permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. | Value | Description | | : | : | | `app_only` | Private to the app that owns the field. | | `read` | Visible to other API consumers. | | `write` | Open for reading and writing by other API consumers. | | `read_and_sf_access` | Visible to other API consumers, including on the storefront. | | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. | ' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: type: string description: 'Namespace for the metafield, for organizational purposes. ' example: Sales Department minLength: 1 maxLength: 64 key: type: string description: 'The name of the field, for example: `location_id`, `color`. ' minLength: 1 maxLength: 64 example: Staff Name value: type: string description: 'The value of the field, for example: `1`, `blue`. ' minLength: 1 maxLength: 65535 example: Ronaldo description: type: string description: 'Description for the metafields. ' minLength: 0 maxLength: 255 example: Name of Staff Member required: - permission_set - namespace - key - value metafield_Full: title: metafield_Full allOf: - type: object properties: id: type: integer description: Unique ID of the *Metafield*. Read-Only. readOnly: true example: 6 - $ref: '#/components/schemas/metafield_Base' - type: object properties: resource_type: type: string description: 'The type of resource with which the metafield is associated. ' example: product enum: - category - brand - product - variant x-required: - post resource_id: maximum: 10000000000 minimum: 0 type: integer description: 'The ID of the resource with which the metafield is associated. ' example: 111 x-required: - post date_created: type: string description: 'Date and time of the metafieldʼs creation. Read-Only. ' readOnly: true format: date-time example: '2018-05-07T20:14:17+00:00' date_modified: type: string description: 'Date and time when the metafield was last updated. Read-Only. ' readOnly: true format: date-time example: '2018-05-07T20:14:17+00:00' x-internal: false MetafieldResponse_2: description: 'Response payload for the BigCommerce API. ' x-internal: false x-examples: {} allOf: - type: object properties: data: $ref: '#/components/schemas/Metafield_2' - $ref: '#/components/schemas/Meta' metafield_Base_2: title: metafield_Base type: object description: Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. x-internal: false properties: key: maxLength: 64 minLength: 1 type: string description: 'The name of the field, for example: `location_id`, `color`. Required for POST. ' example: Location x-required: - post value: maxLength: 65535 minLength: 1 type: string description: 'The value of the field, for example: `1`, `blue`. Required for POST. ' example: 4HG x-required: - post namespace: maxLength: 64 minLength: 1 type: string description: 'Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. ' example: Warehouse Locations x-required: - post permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description |-|-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access description: maxLength: 255 minLength: 0 type: string description: 'Description for the metafields. ' example: Location in the warehouse required: - permission_set - namespace - key - value categoriesTree_Resp: title: categoriesTree_Resp type: object properties: data: type: array items: $ref: '#/components/schemas/categoriesTreeNode_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' description: 'Returns the categories tree, a nested lineage of the categories with parent->child relationship. The Category objects returned are simplified versions of the category objects returned in the rest of this API. ' x-internal: false MetafieldPut: description: 'The model for a PUT to update metafield. ' allOf: - $ref: '#/components/schemas/MetafieldBase_Post_2' x-internal: false MetafieldBase_Post_2: type: object description: 'Common Metafield properties. ' x-internal: false properties: permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description | |:-|:-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| ' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: type: string description: 'Namespace for the metafield, for organizational purposes. ' example: Sales Department minLength: 1 maxLength: 64 key: type: string description: 'The name of the field, for example: `location_id`, `color`. ' minLength: 1 maxLength: 64 example: Staff Name value: type: string description: 'The value of the field, for example: `1`, `blue`. ' minLength: 1 maxLength: 65535 example: Ronaldo description: type: string description: 'Description for the metafields. ' minLength: 0 maxLength: 255 example: Name of Staff Member required: - permission_set - namespace - key - value NotFound: description: Error payload for the BigCommerce API. type: object properties: status: description: '404 HTTP status code. ' type: integer title: description: The error title describing the particular error. type: string type: type: string instance: type: string title: Not Found x-internal: false MetafieldResponse: description: 'Response payload for the BigCommerce API. ' x-internal: false allOf: - type: object properties: data: $ref: '#/components/schemas/Metafield' - $ref: '#/components/schemas/CollectionMeta' error_Base: type: object title: error_Base properties: status: description: 'The HTTP status code. ' type: integer title: description: 'The error title describing the particular error. ' type: string type: type: string description: Error payload for the BigCommerce API. x-internal: false metafield_Base: title: metafield_Base type: object description: Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. x-internal: false properties: key: maxLength: 64 minLength: 1 type: string description: 'The name of the field, for example: `location_id`, `color`. Required for POST. ' example: Location x-required: - post value: maxLength: 65535 minLength: 1 type: string description: 'The value of the field, for example: `1`, `blue`. Required for POST. ' example: 4HG x-required: - post namespace: maxLength: 64 minLength: 1 type: string description: 'Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. ' example: Warehouse Locations x-required: - post permission_set: type: string description: 'Determines the visibility and writeability of the field by other API consumers. |Value|Description |-|-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|' enum: - app_only - read - write - read_and_sf_access - write_and_sf_access description: maxLength: 255 minLength: 0 type: string description: 'Description for the metafields. ' example: Location in the warehouse required: - permission_set - namespace - key - value MetaFieldCollectionResponse: type: object description: 'Response payload for the BigCommerce API. ' properties: data: $ref: '#/components/schemas/Metafield' meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false securitySchemes: X-Auth-Token: name: X-Auth-Token description: '### OAuth scopes | UI Name | Permission | Parameter | |:--|:--|:-| | Information & Settings | read-only | `store_v2_information_read_only`| | Information & Settings | modify | `store_v2_information` | ### 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).' type: apiKey in: header