BigCommerce Docs

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/carts/cart_id/metafields \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "permission_set": "app_only",
  "namespace": "Sales Department",
  "key": "Staff Name",
  "value": "Sam",
  "description": "Name of staff member"
}'

{
  "data": {
    "date_created": "2023-11-15T15:16:35+00:00",
    "date_modified": "2023-11-15T15:16:35+00:00",
    "description": "Name of staff member",
    "id": "24",
    "key": "Staff Name",
    "namespace": "Sales Department",
    "permission_set": "app_only",
    "resource_id": "b810114d-9926-45b7-bba5-7633b251154b",
    "resource_type": "cart",
    "value": "Sam"
  },
  "meta": {}
}

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.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Carts	modify	`store_cart`
Carts	read-only	`store_cart_read_only`
Information & Settings	modify	`store_v2_information`
Information & Settings	read-only	`store_v2_information`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| |Carts|modify|`store_cart`| |Carts |read-only|`store_cart_read_only`| |Information & Settings | modify | `store_v2_information`| |Information & Settings | read-only| `store_v2_information`| ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

cart_idstringRequiredformat: "UUID"

The ID of the Cart to which the transactions belong.

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

permission_setenumRequired

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.

namespacestringRequired1-64 characters

Namespace for the metafield, for organizational purposes.

keystringRequired1-64 characters

The name of the field, for example: location_id, color.

valuestringRequired1-65535 characters

The value of the field, for example: 1, blue.

descriptionstringOptional0-255 characters

Description for the metafields.

Response

A Metafield object.

dataobject

Allows app partners to write custom data to various resources in the API.

metaobject

Response metadata.

Errors

400

Bad Request Error

409

Conflict Error

422

Unprocessable Entity Error

Create Cart Metafield

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Headers

Request

Response

Errors

OAuth scopes

Authentication header

Further reading