cartCreateNamed

Mutationin Multiple carts

Create a cart under a name and switch to it, which is what a new-cart dialog does. The same outcome as cartCreate followed by cartRename and cartSetCurrent, in one call rather than three round trips.

Pass setCurrent: false to add a cart to the list without moving the buyer off the one they are working on.

Arguments

Argument	Type	Description
name	String!
setCurrent	Boolean	Default true

Returns

CartCreateNamedResponse!

Field	Type	Description
cart	Cart	The cart that was created
cartErrors	[CartCreateNamedError!]	Error details if the cart could not be created

Example

Query

mutation CartCreateNamed($name: String!, $setCurrent: Boolean) {
  cartCreateNamed(name: $name, setCurrent: $setCurrent) {
    cart {
      id
      version
      createdAt
      lastModifiedAt
      currency
      customerEmail
      isGuest
      totalQuantity
      deliveryRemarks
      vatNumber
      purchaseOrderNumber
      deliverySplit
      requestedDeliveryDate
      earliestCompleteDeliveryDate
      name
      defaultName
      status
    }
    cartErrors {
      __typename
      ... on ValidationError {
        message
      }
      ... on CartError {
        message
        code
      }
    }
  }
}

Variables

{
  "name": "Example",
  "setCurrent": true
}

Response

{
  "data": {
    "cartCreateNamed": {
      "cart": {
        "id": "id-1",
        "version": "Example",
        "createdAt": "2026-10-01T09:30:00Z",
        "lastModifiedAt": "2026-10-01T09:30:00Z",
        "currency": "EUR",
        "customerEmail": "jane@example.com",
        "isGuest": true,
        "totalQuantity": 1,
        "deliveryRemarks": "Example",
        "vatNumber": "Example",
        "purchaseOrderNumber": "Example",
        "deliverySplit": "COMPLETE",
        "requestedDeliveryDate": "2026-10-01",
        "earliestCompleteDeliveryDate": "2026-10-01",
        "name": "Example",
        "defaultName": "Example",
        "status": "ACTIVE"
      },
      "cartErrors": [
        {
          "__typename": "ValidationError",
          "message": "Example"
        }
      ]
    }
  }
}

The query selects the return type's fields two levels deep; pick the ones you need. The response shows its shape with placeholder values.

Served by

@evolve-framework/commercetools	Resolved
@evolve-framework/medusa	Resolved

Used by

The storefront packages that send it, in these GraphQL documents:

• @evolve-storefront/feature-cart: CartCreateNamed