--- title: Cart - Storefront API description: > A cart represents the merchandise that a buyer intends to purchase, and the estimated cost associated with the cart, throughout a customer's session. Use the [`checkoutUrl`](/docs/api/storefront/2025-07/objects/Cart#field-checkoutUrl) field to direct buyers to Shopify's web checkout to complete their purchase. Learn more about [interacting with carts](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage). api_version: 2025-07 api_name: storefront type: object api_type: graphql source_url: html: 'https://shopify.dev/docs/api/storefront/2025-07/objects/Cart' md: 'https://shopify.dev/docs/api/storefront/2025-07/objects/Cart.md' --- # Cart object A cart represents the merchandise that a buyer intends to purchase, and the estimated cost associated with the cart, throughout a customer's session. Use the [`checkoutUrl`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart#field-checkoutUrl) field to direct buyers to Shopify's web checkout to complete their purchase. Learn more about [interacting with carts](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage). ## Fields * applied​Gift​Cards [\[Applied​Gift​Card!\]!](https://shopify.dev/docs/api/storefront/2025-07/objects/AppliedGiftCard) non-null The gift cards that have been applied to the cart. * attribute [Attribute](https://shopify.dev/docs/api/storefront/2025-07/objects/Attribute) An attribute associated with the cart. * key [String!](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) required ### Arguments The key of the attribute. *** * attributes [\[Attribute!\]!](https://shopify.dev/docs/api/storefront/2025-07/objects/Attribute) non-null The attributes associated with the cart. Attributes are represented as key-value pairs. * buyer​Identity [Cart​Buyer​Identity!](https://shopify.dev/docs/api/storefront/2025-07/objects/CartBuyerIdentity) non-null Information about the buyer that's interacting with the cart. * checkout​Url [URL!](https://shopify.dev/docs/api/storefront/2025-07/scalars/URL) non-null The URL of the checkout for the cart. * cost [Cart​Cost!](https://shopify.dev/docs/api/storefront/2025-07/objects/CartCost) non-null The estimated costs that the buyer will pay at checkout. The costs are subject to change and changes will be reflected at checkout. The `cost` field uses the `buyerIdentity` field to determine [international pricing](https://shopify.dev/custom-storefronts/internationalization/international-pricing). * created​At [Date​Time!](https://shopify.dev/docs/api/storefront/2025-07/scalars/DateTime) non-null The date and time when the cart was created. * delivery [Cart​Delivery!](https://shopify.dev/docs/api/storefront/2025-07/objects/CartDelivery) non-null The delivery properties of the cart. * delivery​Groups [Cart​Delivery​Group​Connection!](https://shopify.dev/docs/api/storefront/2025-07/connections/CartDeliveryGroupConnection) non-null The delivery groups available for the cart, based on the buyer identity default delivery address preference or the default address of the logged-in customer. * first [Int](https://shopify.dev/docs/api/storefront/2025-07/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/2025-07/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) Returns the elements that come before the specified cursor. * reverse [Boolean](https://shopify.dev/docs/api/storefront/2025-07/scalars/Boolean) Default:false Reverse the order of the underlying list. * with​Carrier​Rates [Boolean](https://shopify.dev/docs/api/storefront/2025-07/scalars/Boolean) Default:false Whether to include [carrier-calculated delivery rates](https://help.shopify.com/en/manual/shipping/setting-up-and-managing-your-shipping/enabling-shipping-carriers) in the response. By default, only static shipping rates are returned. This argument requires mandatory usage of the [`@defer` directive](https://shopify.dev/docs/api/storefront#directives). For more information, refer to [fetching carrier-calculated rates for the cart using `@defer`](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/defer#fetching-carrier-calculated-rates-for-the-cart-using-defer). *** * discount​Allocations [\[Cart​Discount​Allocation!\]!](https://shopify.dev/docs/api/storefront/2025-07/interfaces/CartDiscountAllocation) non-null The discounts that have been applied to the entire cart. * discount​Codes [\[Cart​Discount​Code!\]!](https://shopify.dev/docs/api/storefront/2025-07/objects/CartDiscountCode) non-null The case-insensitive discount codes that the customer added at checkout. * id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) non-null A globally-unique ID. * lines [Base​Cart​Line​Connection!](https://shopify.dev/docs/api/storefront/2025-07/connections/BaseCartLineConnection) non-null A list of lines containing information about the items the customer intends to purchase. * first [Int](https://shopify.dev/docs/api/storefront/2025-07/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/2025-07/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) Returns the elements that come before the specified cursor. * reverse [Boolean](https://shopify.dev/docs/api/storefront/2025-07/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * metafield [Metafield](https://shopify.dev/docs/api/storefront/2025-07/objects/Metafield) Token access required A [custom field](https://shopify.dev/docs/apps/build/custom-data), including its `namespace` and `key`, that's associated with a Shopify resource for the purposes of adding and storing additional information. * namespace [String](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) ### Arguments The container the metafield belongs to. If omitted, the app-reserved namespace will be used. * key [String!](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) required The identifier for the metafield. *** * metafields [\[Metafield\]!](https://shopify.dev/docs/api/storefront/2025-07/objects/Metafield) non-null Token access required A list of [custom fields](https://shopify.dev/docs/apps/build/custom-data) that a merchant associates with a Shopify resource. * identifiers [\[Has​Metafields​Identifier!\]!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/HasMetafieldsIdentifier) required ### Arguments The list of metafields to retrieve by namespace and key. The input must not contain more than `250` values. *** * note [String](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) A note that's associated with the cart. For example, the note can be a personalized message to the buyer. * total​Quantity [Int!](https://shopify.dev/docs/api/storefront/2025-07/scalars/Int) non-null The total number of items in the cart. * updated​At [Date​Time!](https://shopify.dev/docs/api/storefront/2025-07/scalars/DateTime) non-null The date and time when the cart was updated. * estimated​Cost [Cart​Estimated​Cost!](https://shopify.dev/docs/api/storefront/2025-07/objects/CartEstimatedCost) non-nullDeprecated *** ## Map ### Possible type in * [Metafield​Parent​Resource](https://shopify.dev/docs/api/storefront/2025-07/unions/MetafieldParentResource) *** ## Queries * [cart](https://shopify.dev/docs/api/storefront/2025-07/queries/cart) query Returns a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart) by its ID. The cart contains the merchandise lines a buyer intends to purchase, along with estimated costs, applied discounts, gift cards, and delivery options. Use the [`checkoutUrl`](https://shopify.dev/docs/api/storefront/latest/queries/cart#returns-Cart.fields.checkoutUrl) field to redirect buyers to Shopify's web checkout when they're ready to complete their purchase. For more information, refer to [Manage a cart with the Storefront API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage). * id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. *** *** ## Cart Queries ### Queried by * [cart](https://shopify.dev/docs/api/storefront/2025-07/queries/cart) *** ## Mutations * [cart​Attributes​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartAttributesUpdate) mutation Updates the attributes on a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). Attributes are custom key-value pairs that store additional information, such as gift messages, special instructions, or order notes. * attributes [\[Attribute​Input!\]!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/AttributeInput) required ### Arguments An array of key-value pairs that contains additional information about the cart. The input must not contain more than `250` values. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required The ID of the cart. *** * [cart​Buyer​Identity​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartBuyerIdentityUpdate) mutation Updates the buyer identity on a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart), including contact information, location, and checkout preferences. The buyer's country determines [international pricing](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/international-pricing) and should match their shipping address. Use this mutation to associate a logged-in customer via access token, set a B2B company location, or configure checkout preferences like delivery method. Preferences prefill checkout fields but don't sync back to the cart if overwritten at checkout. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * buyer​Identity [Cart​Buyer​Identity​Input!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartBuyerIdentityInput) required The customer associated with the cart. Used to determine [international pricing](https://shopify.dev/custom-storefronts/internationalization/international-pricing). Buyer identity should match the customer's shipping address. *** * [cart​Create](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartCreate) mutation Creates a new [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart) for a buyer session. You can optionally initialize the cart with merchandise lines, discount codes, gift card codes, buyer identity for international pricing, and custom attributes. The returned cart includes a `checkoutUrl` that directs the buyer to complete their purchase. * input [Cart​Input](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartInput) ### Arguments The fields used to create a cart. *** * [cart​Delivery​Addresses​Add](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDeliveryAddressesAdd) mutation Adds delivery addresses to a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). A cart can have up to 20 delivery addresses. One address can be marked as selected for checkout, and addresses can optionally be marked as one-time use so they aren't saved to the customer's account. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * addresses [\[Cart​Selectable​Address​Input!\]!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartSelectableAddressInput) required A list of delivery addresses to add to the cart. The input must not contain more than `250` values. *** * [cart​Delivery​Addresses​Remove](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDeliveryAddressesRemove) mutation Removes delivery addresses from a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart) by their IDs, allowing batch removal in a single request. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * address​Ids [\[ID!\]!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required A list of delivery addresses by handle to remove from the cart. The input must not contain more than `250` values. *** * [cart​Delivery​Addresses​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDeliveryAddressesUpdate) mutation Updates one or more delivery addresses on a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). Each address can be modified to change its details, set it as the pre-selected address for checkout, or mark it for one-time use so it isn't saved to the customer's account. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * addresses [\[Cart​Selectable​Address​Update​Input!\]!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartSelectableAddressUpdateInput) required The delivery addresses to update. The input must not contain more than `250` values. *** * [cart​Discount​Codes​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDiscountCodesUpdate) mutation Updates the discount codes applied to a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). This mutation replaces all existing discount codes with the provided list, so pass an empty array to remove all codes. Discount codes are case-insensitive. After updating, check each [`CartDiscountCode`](https://shopify.dev/docs/api/storefront/2025-07/objects/CartDiscountCode) in the cart's [`discountCodes`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart#field-Cart.fields.discountCodes) field to see whether the code is applicable to the cart's current contents. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * discount​Codes [\[String!\]](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) The case-insensitive discount codes that the customer added at checkout. The input must not contain more than `250` values. *** * [cart​Gift​Card​Codes​Remove](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartGiftCardCodesRemove) mutation Removes gift cards from a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart) using their IDs. You can retrieve the IDs of applied gift cards from the cart's [`appliedGiftCards`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart#field-Cart.fields.appliedGiftCards) field. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * applied​Gift​Card​Ids [\[ID!\]!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required The gift cards to remove. The input must not contain more than `250` values. *** * [cart​Gift​Card​Codes​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartGiftCardCodesUpdate) mutation Updates the gift card codes applied to the cart. Unlike [`cartGiftCardCodesAdd`](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartGiftCardCodesAdd), which adds codes without replacing existing ones, this mutation sets the gift card codes for the cart. Gift card codes are case-insensitive. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * gift​Card​Codes [\[String!\]!](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) required The case-insensitive gift card codes. The input must not contain more than `250` values. *** * [cart​Lines​Add](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartLinesAdd) mutation Adds one or more merchandise lines to an existing [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). Each line specifies the [product variant](https://shopify.dev/docs/api/storefront/2025-07/objects/ProductVariant) to purchase. Quantity defaults to `1` if not provided. You can add up to 250 lines in a single request. Use [`CartLineInput`](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartLineInput) to configure each line's merchandise, quantity, selling plan, custom attributes, and any parent relationships for nested line items such as warranties or add-ons. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * lines [\[Cart​Line​Input!\]!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartLineInput) required A list of merchandise lines to add to the cart. The input must not contain more than `250` values. *** * [cart​Lines​Remove](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartLinesRemove) mutation Removes one or more merchandise lines from a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). Accepts up to 250 line IDs per request. Returns the updated cart along with any errors or warnings. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * line​Ids [\[ID!\]!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required The merchandise line IDs to remove. The input must not contain more than `250` values. *** * [cart​Lines​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartLinesUpdate) mutation Updates one or more merchandise lines on a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). You can modify the quantity, swap the merchandise, change custom attributes, or update the selling plan for each line. You can update a maximum of 250 lines per request. Omitting the [`attributes`](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartLinesUpdate#arguments-lines.fields.attributes) field or setting it to null preserves existing line attributes. Pass an empty array to clear all attributes from a line. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * lines [\[Cart​Line​Update​Input!\]!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartLineUpdateInput) required The merchandise lines to update. The input must not contain more than `250` values. *** * [cart​Note​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartNoteUpdate) mutation Updates the note on a [`Cart`](https://shopify.dev/docs/api/storefront/2025-07/objects/Cart). The note is a text field that stores additional information, such as a personalized message from the buyer or special instructions for the order. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * note [String!](https://shopify.dev/docs/api/storefront/2025-07/scalars/String) required The note on the cart. *** * [cart​Selected​Delivery​Options​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartSelectedDeliveryOptionsUpdate) mutation Updates the selected delivery option for one or more [`CartDeliveryGroup`](https://shopify.dev/docs/api/storefront/2025-07/objects/CartDeliveryGroup) objects in a cart. Each delivery group represents items shipping to a specific address and offers multiple delivery options with different costs and methods. Use this mutation when a customer chooses their preferred shipping method during checkout. The [`deliveryOptionHandle`](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartSelectedDeliveryOptionInput#field-CartSelectedDeliveryOptionInput.fields.deliveryOptionHandle) identifies which [`CartDeliveryOption`](https://shopify.dev/docs/api/storefront/2025-07/objects/CartDeliveryOption) to select for each delivery group. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/2025-07/scalars/ID) required ### Arguments The ID of the cart. * selected​Delivery​Options [\[Cart​Selected​Delivery​Option​Input!\]!](https://shopify.dev/docs/api/storefront/2025-07/input-objects/CartSelectedDeliveryOptionInput) required The selected delivery options. The input must not contain more than `250` values. *** *** ## Cart Mutations ### Mutated by * [cart​Attributes​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartAttributesUpdate) * [cart​Buyer​Identity​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartBuyerIdentityUpdate) * [cart​Create](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartCreate) * [cart​Delivery​Addresses​Add](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDeliveryAddressesAdd) * [cart​Delivery​Addresses​Remove](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDeliveryAddressesRemove) * [cart​Delivery​Addresses​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDeliveryAddressesUpdate) * [cart​Discount​Codes​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartDiscountCodesUpdate) * [cart​Gift​Card​Codes​Remove](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartGiftCardCodesRemove) * [cart​Gift​Card​Codes​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartGiftCardCodesUpdate) * [cart​Lines​Add](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartLinesAdd) * [cart​Lines​Remove](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartLinesRemove) * [cart​Lines​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartLinesUpdate) * [cart​Note​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartNoteUpdate) * [cart​Selected​Delivery​Options​Update](https://shopify.dev/docs/api/storefront/2025-07/mutations/cartSelectedDeliveryOptionsUpdate) *** ## Interfaces * * [Has​Metafields](https://shopify.dev/docs/api/storefront/2025-07/interfaces/HasMetafields) interface * [Node](https://shopify.dev/docs/api/storefront/2025-07/interfaces/Node) interface *** ## Cart Implements ### Implements * [Has​Metafields](https://shopify.dev/docs/api/storefront/2025-07/interfaces/HasMetafields) * [Node](https://shopify.dev/docs/api/storefront/2025-07/interfaces/Node)