openapi: 3.2.0 info: title: Bigcommerce Metafields API version: '' contact: name: BigCommerce url: https://www.bigcommerce.com email: support@bigcommerce.com termsOfService: https://www.bigcommerce.com/terms description: 'Operations tagged Metafields across 7 of this provider''s published API definitions: carts-openapi-original.yml, catalog-brands-openapi-original.yml, catalog-categories-openapi-original.yml, catalog-product-variants-openapi-original.yml, catalog-products-openapi-original.yml, channels-openapi-original.yml, orders-openapi-original.yml. Each path carries the servers of the definition it was published in.' 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: Meta Fields paths: /carts/{cart_id}/metafields: parameters: - $ref: '#/components/parameters/cart_id' - $ref: '#/components/parameters/Accept' get: summary: BigCommerce Get Cart Metafields tags: - Meta Fields 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: - Meta Fields description: 'Create a cart `Metafield`. If 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.' 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 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 /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: - Meta Fields 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: - Meta Fields 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: - Meta Fields description: Deletes a `Metafield`. operationId: deleteCartMetafield responses: '204': description: "An empty response. \n" 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 /catalog/brands/{brand_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/BrandIdParam' get: tags: - Meta Fields 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: - Meta Fields 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 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 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 /catalog/brands/{brand_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/BrandIdParam' - $ref: '#/components/parameters/MetafieldIdParam' get: tags: - Meta Fields 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: - Meta Fields summary: BigCommerce Update a Brand Metafield description: 'Updates a *Brand Metafield*. **Required Fields** * none **Read-Only Fields** * id * These fields can only be modified by the app (API credentials) that created the metafield: * namespace * key * permission_set **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. * 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 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: - Meta Fields 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: {} 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 /catalog/categories/{category_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/CategoryIdParam' get: tags: - Meta Fields 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: - Meta Fields 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) 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 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 /catalog/categories/{category_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/CategoryIdParam' - $ref: '#/components/parameters/MetafieldIdParam' get: tags: - Meta Fields 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: - Meta Fields summary: BigCommerce Update a Category Metafield description: 'Updates a *Category Metafield*. **Required Fields** * none **Read-Only Fields** * id * These fields can only be modified by the app (API credentials) that created the metafield: * namespace * key * permission_set **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.' 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: - Meta Fields summary: BigCommerce Delete a Category Metafield description: Deletes a *Category Metafield*. operationId: deleteCategoryMetafield responses: '204': description: '' content: {} 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 /catalog/products/{product_id}/variants/{variant_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ProductIdParam' - $ref: '#/components/parameters/VariantIdParam' get: tags: - Meta Fields 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: - Meta Fields 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 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 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 /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: - Meta Fields 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: - Meta Fields summary: BigCommerce Update Product Variant Metafields description: 'Updates a product variant *Metafield*. **Required Fields:** * none **Read-Only Fields** * id * These fields can only be modified by the app (API credentials) that created the metafield: * namespace * key * permission_set **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.' 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: - Meta Fields summary: BigCommerce Delete a Product Variant Metafield description: Deletes a product variant *Metafield*. operationId: deleteProductVariantMetafield responses: '204': description: '' content: {} 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 /catalog/products/{product_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ProductIdParam_2' get: tags: - Meta Fields 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: - Meta Fields 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 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 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 /catalog/products/{product_id}/metafields/{metafield_id}: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ProductIdParam_2' - $ref: '#/components/parameters/MetafieldIdParam' get: tags: - Meta Fields 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: - Meta Fields summary: BigCommerce Update a Product Metafield description: 'Updates a *Product Metafield*. **Required Fields** * none **Read-Only Fields** * id * These fields can only be modified using the API account that created the metafield: * `namespace` * `key` * `permission_set` * `value` **Usage Notes** * 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: - Meta Fields summary: BigCommerce Delete a Product Metafield description: Deletes a *Product Metafield*. operationId: deleteProductMetafield responses: '204': description: '' content: {} 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 /channels/{channel_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/channel_id_path_param' get: summary: BigCommerce Get Channel Metafields tags: - Meta Fields 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: - Meta Fields 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 in the Help Center.' 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 /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: - Meta Fields 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: - Meta Fields 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: - Meta Fields description: Deletes a single channel metafield. 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 /orders/{order_id}/metafields: parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/OrderIdParam' get: summary: BigCommerce Get Order Metafields tags: - Meta Fields 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: - Meta Fields 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' 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 /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: - Meta Fields 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: - Meta Fields 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: - Meta Fields description: Deletes a `Metafield`. operationId: deleteOrderMetafield responses: '204': description: 'An empty response. ' 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 components: schemas: 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_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 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 MetaFieldCollectionResponse: type: object description: 'Response payload for the BigCommerce API. ' properties: data: $ref: '#/components/schemas/Metafield' meta: $ref: '#/components/schemas/CollectionMeta' 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 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' 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 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 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 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 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 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 metaEmpty_Full: type: object title: Response meta properties: {} additionalProperties: true description: Response metadata. 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 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_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_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 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 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. 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_2: allOf: - $ref: '#/components/schemas/error_Base' - type: object properties: errors: type: object properties: {} additionalProperties: true title: DetailedErrors title: ErrorResponse 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' 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 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 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 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 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 MetafieldPut: description: 'The model for a PUT to update metafield. ' allOf: - $ref: '#/components/schemas/MetafieldBase_Post_2' x-internal: false 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: {} parameters: ContentType: name: Content-Type in: header required: true schema: type: string default: application/json DirectionParam: name: direction description: 'Sort direction. Acceptable values are: `asc`, `desc`. ' required: false in: query schema: type: string enum: - asc - desc PageParam: name: page description: 'Specifies the page number in a limited (paginated) list of products. ' required: false in: query schema: type: integer 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 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 MetafieldNamespaceParam: name: namespace in: query description: Filter based on a metafieldʼs namespaces. required: false schema: type: string MetafieldKeyParam: name: key in: query description: Filter based on a metafieldʼs key. required: false schema: type: string 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_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 BrandIdParam: name: brand_id in: path description: 'The ID of the `Brand` to which the resource belongs. ' required: true schema: type: integer MetafieldIdParam: name: metafield_id in: path description: 'The ID of the `Metafield`. ' required: true schema: type: integer 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 CategoryIdParam: name: category_id in: path description: 'The ID of the `Category` to which the resource belongs. ' required: true schema: type: integer 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 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 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 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 ProductIdParam_2: name: product_id in: path description: 'The ID of the `Product` to which the resource belongs. ' required: true schema: type: integer 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 DirectionParam_2: name: direction description: 'Sort direction. Acceptable values are: `asc`, `desc`.' required: false in: query schema: type: string enum: - asc - desc channel_id_path_param: name: channel_id description: The ID of a channel. in: path required: true schema: type: integer format: int64 MetafieldNamespaceParam_2: name: namespace in: query description: Filter based on a metafieldʼs namespace. required: false schema: type: string MetafieldKeyParam_2: name: key in: query description: 'Filter based on a metafieldʼs key. ' required: false schema: type: string MetafieldKeyParam_3: name: key in: query description: 'Filter based on a metafieldʼs key. ' required: false schema: type: string 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 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 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' securitySchemes: X-Auth-Token: name: X-Auth-Token description: '### OAuth scopes | UI Name | Permission | Parameter | |:--|:--|:-| |Carts|modify|`store_cart`| |Carts |read-only|`store_cart_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).' type: apiKey in: header x-refined-from: - carts-openapi-original.yml - catalog-brands-openapi-original.yml - catalog-categories-openapi-original.yml - catalog-product-variants-openapi-original.yml - catalog-products-openapi-original.yml - channels-openapi-original.yml - orders-openapi-original.yml