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:
ty
# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-metafields-api-openapi.yml