> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

**GraphQL Storefront API: Cart Metafields**

# Working with cart metafields

Cart metafields let you add custom metadata to a cart to display product information. Cart metafields are key-value pairs. You can work with them using both the GraphQL Storefront API and the REST Management API.

## Example queries and mutations

### Query cart metafields

#### Request

**`Example query: Get cart metafields`**

```graphql title="Example query: Get cart metafields"  showLineNumbers={false}
 query getCartMetafields {
   site{
     cart{
      metafields(namespace: "bc_storefront"){
        edges{
          node{
            id
            key
            value
          }
        }
      }
    }
  }
}
```

#### Response

**`Example query: Get cart metafields`**

```json title="Example query: Get cart metafields" showLineNumbers={false}
{
  "data": {
    "site": {
      "cart": {
        "metafields": {
          "edges": [
            {
              "node": {
                "id": "TWV0YWZpZWxkczo1NQ==",
                "key": "size",
                "value": "small"
              }
            }
          ]
        }
      }
    }
  }
}
```

### Create a cart metafield

> **Note**
>
> The platform limits are as follows:
>
> * 10 metafields per client (with customer ID or without ID) per cart
> * 250 metafields in total for a single cart  (e.g., 25 clients \* 10 metafields)

#### Request

**`Example mutation: Create a cart metafield`**

```graphql title="Example mutation: Create a cart metafield"  showLineNumbers={false}
mutation createCartMetafield { 
 cart {
  createCartMetafield(input:{
    cartEntityId: "4a5fd706-beb9-41b5-9ac2-01593b471168"
    data: {
      key: "size"
      value: "small"
    }
  }) {
    metafield {
      id
      entityId
      key
      value
    }
    errors {
      ...on Error {
        message
      }
    }
  }
}
}
```

#### Response

**`Example mutation: Create a cart metafield`**

```json title="Example mutation: Create a cart metafield"
{
"data": {
  "cart": {
    "createCartMetafield": {
      "metafield": {
        "id": "TWV0YWZpZWxkczo1Mw==",
        "entityId": 53,
        "key": "size",
        "value": "small"
      },
      "errors": []
    }
  }
}
}
```

### Update a cart metafield

#### Request

**`Example mutation: Update a cart metafield`**

```graphql title="Example mutation: Update a cart metafield" 
mutation updateCartMetafield {
 cart {
  updateCartMetafield(input:{
    cartEntityId: "4a5fd706-beb9-41b5-9ac2-01593b471168"
    metafieldEntityId:53
    data: {
      key: "Size",
  value: "medium"
    }
  }) {
    metafield {
      id
      entityId
      key
      value
    }
    errors {
      ...on Error {
        message
      }
    }
  }
}
}

```

#### Response

**`Example mutation: Update a cart metafield`**

```json title="Example mutation: Update a cart metafield" showLineNumbers={false}
 {
  "data": {
    "cart": {
      "updateCartMetafield": {
        "metafield": {
          "id": "TWV0YWZpZWxkczo1Mw==",
          "entityId": 53,
          "key": "Size",
          "value": "medium"
        },
        "errors": []
      }
    }
  }
}
```

### Delete a cart metafield

#### Request

**`Example mutation: Delete a cart metafield`**

```graphql title="Example mutation: Delete a cart metafield"  showLineNumbers={false}
 mutation deleteCartMetafield {
  cart {
   deleteCartMetafield(input:{
     cartEntityId: "4a5fd706-beb9-41b5-9ac2-01593b471168"
     metafieldEntityId: 53
  }) {
  errors {
        ... on NotFoundError {
          __typename
          message
        }
        ... on ValidationError {
          __typename
          message
          path
        }
        ... on NotAuthorisedError {
          __typename
        }
      }
    }
  }
}
```

#### Response

**`Example mutation: Delete a cart metafield`**

```json title="Example mutation: Delete a cart metafield" showLineNumbers={false}
{
  "data": {
    "cart": {
      "deleteCartMetafield": {
        "errors": []
      }
    }
  }
}
```

## Resources

### GraphQL documentation

* [GraphQL Storefront API overview](/developer/docs/storefront/guides/graphql-storefront-api)
* [GraphQL Storefront API: Carts and Checkout](/developer/docs/admin/checkout-and-cart/custom-checkouts/graphql-storefront)
* [Authenticating requests to the GraphQL Storefront API](/developer/docs/storefront/guides/graphql-storefront-api/authentication)
* [Authentication and Example Requests: BigCommerce-generated JWTs](/developer/docs/overview/api-fundamentals/api-accounts#bigcommerce-generated-jwts)
* [GraphQL Storefront Playground](/developer/api-reference/rest/storefront/overview)