---
title: cartMetafieldsSet - Storefront API
description: >-
  Sets [`Metafield`](/docs/api/storefront/2026-10/objects/Metafield) values on a
  cart, creating new metafields or updating existing ones. Accepts

  up to 25 metafields per request.


  Cart metafields can automatically copy to order metafields when an order is

  created, if there's a matching order metafield definition with the [cart to
  order
  copyable](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable)

  capability enabled.


  > Note:

  > This mutation doesn't trigger [Shopify

  Functions](https://shopify.dev/docs/api/functions). Changes aren't available

  to Shopify Functions until the buyer goes to checkout or performs another cart

  interaction that triggers the functions.
api_version: 2026-10
source_url:
  html: 'https://shopify.dev/docs/api/storefront/latest/mutations/cartMetafieldsSet'
  md: >-
    https://shopify.dev/docs/api/storefront/latest/mutations/cartMetafieldsSet.md
api_name: storefront
api_type: graphql
type: mutation
---

# cart​Metafields​Set

mutation

Sets [`Metafield`](https://shopify.dev/docs/api/storefront/2026-10/objects/Metafield) values on a cart, creating new metafields or updating existing ones. Accepts up to 25 metafields per request.

Cart metafields can automatically copy to order metafields when an order is created, if there's a matching order metafield definition with the [cart to order copyable](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable) capability enabled.

***

**Note:** This mutation doesn\&#39;t trigger \<a href="https://shopify.dev/docs/api/functions">Shopify Functions\</a>. Changes aren\&#39;t available to Shopify Functions until the buyer goes to checkout or performs another cart interaction that triggers the functions.

***

## Arguments

* metafields

  [\[Cart​Metafields​Set​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartMetafieldsSetInput)

  required

  The list of Cart metafield values to set. Maximum of 25.

  The input must not contain more than `250` values.

***

## Cart​Metafields​Set​Payload returns

* metafields

  [\[Metafield!\]](https://shopify.dev/docs/api/storefront/latest/objects/Metafield)

  The list of cart metafields that were set.

* user​Errors

  [\[Metafields​Set​User​Error!\]!](https://shopify.dev/docs/api/storefront/latest/objects/MetafieldsSetUserError)

  non-null

  The list of errors that occurred from executing the mutation.

***

## Examples

* ### cartMetafieldsSet reference