Cart

A shopping cart — the buyer-facing aggregate that holds items, totals, buyer identity, addresses, selected shipping and payment methods, gift cards and discount codes through to checkout completion.

type Cart implements Node {
  appliedGiftCards: [CartAppliedGiftCard!]!
  attributes: [CartAttribute!]!
  availablePaymentMethods: [PaymentMethod!]!
  availableShippingMethods(
    address: ShippingAddressInput!
  ): AvailableShippingMethodsPayload!
  billingAddress: MailingAddress
  buyerIdentity: CartBuyerIdentity
  checkoutUrl: URL
  completedOrder: Order
  cost: CartCost!
  createdAt: DateTime!
  discountAllocations: [CartDiscountAllocation!]!
  discountCodes: [CartDiscountCode!]!
  email: String
  id: ID!
  lines(
    after: String
    before: String
    first: Float
    last: Float
  ): CartLineConnection!
  note: String
  phone: String
  recommendations(
    first: Int = 4
  ): CartRecommendations
  requiresShipping: Boolean!
  selectedPaymentInstrument: String
  selectedPaymentMethod: PaymentMethod
  selectedPaymentProvider: PaymentProvider
  selectedShippingMethod: CartShippingMethod
  shippingAddress: MailingAddress
  status: CartStatus!
  totalQuantity: Int!
  updatedAt: DateTime!
  warnings: [CartWarning!]!
}

Fields

Cart.appliedGiftCards ● [CartAppliedGiftCard!]! non-null object

Gift cards attached to the cart. Each card is debited by its appliedAmount when the cart completes.

Cart.attributes ● [CartAttribute!]! non-null object

Cart-level custom attributes (free-form key/value). Use for cart-wide metadata such as B2B PO number or marketing source. Replace (not merge) the list with cartUpdateAttributes.

Cart.availablePaymentMethods ● [PaymentMethod!]! non-null object

Available payment methods for this cart — deduplicated per type, sorted by merchant priority.

Cart.availableShippingMethods ● AvailableShippingMethodsPayload! non-null object

Shipping methods available for this cart at the given destination. Reads the cart subtotal and weight directly — for pre-cart preview (e.g. a product detail page calculator) use the top-level availableShippingMethods(address, cart) query instead. Returns an empty methods list plus a DIGITAL_ONLY_NO_SHIPPING user error when the cart has no shippable items; the storefront can use this to skip the shipping step entirely.

Cart.availableShippingMethods.address ● ShippingAddressInput! non-null input

Destination address — country (ISO 3166-1 alpha-2), region, postal code and city

Cart.billingAddress ● MailingAddress object

Billing address attached to the cart via cartSetBillingAddress. Null when the buyer reuses the shipping address as billing (the order will then mirror the shipping address).

Cart.buyerIdentity ● CartBuyerIdentity object

Buyer identity attached to the cart (email, phone, country and language hints). Null on a fresh cart before any identity is captured.

Cart.checkoutUrl ● URL scalar

Hosted checkout URL the storefront may redirect to as a fallback. The recommended flow is to drive checkout through SDK mutations (cartSetShippingAddress, cartSelectShippingMethod, cartSelectPaymentMethod, cartComplete).

Cart.completedOrder ● Order object

The order that this cart converted into. Populated only when status is CONVERTED — null on every other status. Use this to render the order confirmation page (subtotals, accessToken for guest tracking) directly off the cart you already loaded, without a second orderByToken round-trip.

Cart.cost ● CartCost! non-null object

Cost breakdown for the cart (subtotal, tax, shipping, discount, grand total).

Cart.createdAt ● DateTime! non-null scalar

When the cart was created (ISO 8601).

Cart.discountAllocations ● [CartDiscountAllocation!]! non-null object

Per-code discount amounts that make up cost.totalDiscount. Render line-item discount breakdown from this list.

Cart.discountCodes ● [CartDiscountCode!]! non-null object

Discount codes attached to the cart with their applicability flag.

Cart.email ● String scalar

Convenience accessor — buyer email as last set via cartUpdateBuyerIdentity. The same value is available on buyerIdentity.email.

Cart.id ● ID! non-null scalar

Stable cart identifier — persist in a cookie / local store between sessions.

Cart.lines ● CartLineConnection! non-null object

Lines in the cart (paginated, Relay Connection).

Cart.lines.after ● String scalar

Cursor for forward pagination (cursor of the last edge from the previous page)

Cart.lines.before ● String scalar

Cursor for backward pagination (cursor of the first edge from the next page)

Cart.lines.first ● Float scalar

Number of lines to return from the start (forward pagination, max 100)

Cart.lines.last ● Float scalar

Number of lines to return from the end (backward pagination, max 100)

Cart.note ● String scalar

Buyer-supplied note (e.g. delivery instructions). Free-form, surfaced to the merchant on the order.

Cart.phone ● String scalar

Convenience accessor — buyer phone as last set via cartUpdateBuyerIdentity. The same value is available on buyerIdentity.phone.

Cart.recommendations ● CartRecommendations object

Product recommendations based on cart contents

Cart.recommendations.first ● Int scalar

Number of cart-based recommendations per bucket (default 4, max 100)

Cart.requiresShipping ● Boolean! non-null scalar

True when at least one line in the cart requires physical shipping. False when every line is non-physical (digital, gift card, service, subscription). Use as the single signal to render or skip the shipping step in checkout.

Cart.selectedPaymentInstrument ● String scalar

Optional concrete instrument code selected within selectedPaymentMethod (e.g. "blik", "mb", "154"). Set when the buyer clicks a specific instrument tile on the storefront (per PaymentMethod.instruments). Pre-payment intent: copied to Order.paymentInstrument on cartComplete. Cross-reference with availablePaymentMethods.methods[].instruments[] to resolve displayName / brandImage { url }.

Cart.selectedPaymentMethod ● PaymentMethod object

The payment method currently selected on the cart. Null until the buyer picks a method via cartSelectPaymentMethod.

Cart.selectedPaymentProvider ● PaymentProvider enum

Provider the buyer picked for the selected method (the preferredProvider echoed back from cartSelectPaymentMethod). Use it to restore the exact picker tile after a reload when the storefront renders one tile per provider — selectedPaymentMethod.type alone cannot tell a gateway pay-by-link apart from a manual bank transfer. Null when the buyer never passed a provider.

Cart.selectedShippingMethod ● CartShippingMethod object

The shipping method currently selected on the cart (label + cost). Null until the buyer picks a method.

Cart.shippingAddress ● MailingAddress object

Shipping address attached to the cart via cartSetShippingAddress. Null until set.

Cart.status ● CartStatus! non-null enum

Lifecycle status — ACTIVE / RECOVERED are editable; ABANDONED is a recovery flag a deliberate buyer action revives in place; CONVERTED / EXPIRED are terminal. Check this on SSR before rendering the checkout form: a CONVERTED cart should redirect (typically to the order confirmation when completedOrder is populated) instead of presenting a form whose first mutation fails with CartErrorCode.ALREADY_COMPLETED.

Cart.totalQuantity ● Int! non-null scalar

Sum of quantity across all lines — the badge number for the cart icon.

Cart.updatedAt ● DateTime! non-null scalar

When the cart was last modified (ISO 8601).

Cart.warnings ● [CartWarning!]! non-null object

Non-fatal advisories computed at query time. Currently emitted: PAYMENT_SELECTION_STALE when selectedPaymentMethod / selectedPaymentInstrument are no longer in live gateway capabilities (storefront re-prompts the buyer). Read-only — backend state is not mutated.

Interfaces

Node interface

GraphQL Node interface — universal ID-based lookup

Returned By

cart query

Member Of

CartAddLinesPayload object ● CartApplyGiftCardPayload object ● CartClearPaymentSelectionPayload object ● CartCreatePayload object ● CartDiscountCodesUpdatePayload object ● CartDowngradeOnLogoutPayload object ● CartMergePayload object ● CartRecoveryRedeemPayload object ● CartRemoveGiftCardPayload object ● CartRemoveLinesPayload object ● CartSelectPaymentMethodPayload object ● CartSelectShippingMethodPayload object ● CartSetBillingAddressPayload object ● CartSetShippingAddressPayload object ● CartUpdateAttributesPayload object ● CartUpdateBuyerIdentityPayload object ● CartUpdateGiftCardRecipientPayload object ● CartUpdateLinesPayload object ● CartUpdateNotePayload object