Cart

Represents a cart in the store, exposing totals, items, discounts, shipping, and payment information for GraphQL APIs.

Type Definition

type Cart {
  id: String
  createdAt: String
  customer: Customer
  discounts: [CartDiscount]
  tags: [String]
  subtotalPrice: Float
  totalPrice: Float
  currency: String
  totalNetPrice: Float
  totalTax: Float
  taxLines: [CartTaxLine]
  customerNote: String
  paymentMethods: [CartPaymentMethod]
  paymentFee: Float
  shippingMethods: [CartShippingMethod]
  shippingPrice: Float
  lines: [CartLineItem]
  physicalLines: [CartLineItem]
  lineCount: Int
  shippingAddress: Address
  billingAddress: Address
  checkoutUrl: String
}

Fields

Relationships

• customer: Links to the Customer object representing the customer associated with the cart, if any.
• discounts: An array of CartDiscount objects representing discounts applied to the cart.
• taxLines: An array of CartTaxLine objects detailing tax breakdowns for the cart.
• paymentMethods: An array of CartPaymentMethod objects describing available payment methods.
• shippingMethods: An array of CartShippingMethod objects describing available shipping options.
• lines and physicalLines: Arrays of CartLineItem objects representing all items and physical items in the cart respectively.
• shippingAddress and billingAddress: Address objects representing the respective addresses for the cart.

These relationships allow traversal from the cart to related entities, enabling detailed queries about the cart’s contents, pricing, and fulfillment.

Usage Examples

Basic Query

Fetch a cart by its ID with key summary fields:

query GetCart {
  cart(id: "12345") {
    id
    createdAt
    subtotalPrice
    totalPrice
    currency
    lineCount
    checkoutUrl
  }
}

Field Selection

Retrieve detailed pricing, discounts, and tags for a cart:

query CartPricingDetails {
  cart(id: "12345") {
    subtotalPrice
    totalNetPrice
    totalTax
    totalPrice
    discounts {
      code
      amount
    }
    tags
  }
}

Nested Queries

Access nested objects such as customer info, shipping address, and cart line items:

query CartWithDetails {
  cart(id: "12345") {
    id
    customer {
      id
      firstName
      lastName
      email
    }
    shippingAddress {
      address1
      city
      postalCode
      country
    }
    lines {
      productId
      quantity
      title
      variantId
      price
    }
  }
}

Filtering and Sorting

Since the Cart type itself does not expose filtering or sorting fields, these operations are typically performed at the query level (e.g., when querying multiple carts). However, you can filter line items client-side by examining fields such as physicalLines to isolate physical products.

Example: Query only physical items in the cart:

query PhysicalItemsInCart {
  cart(id: "12345") {
    physicalLines {
      productId
      quantity
      title
      price
    }
  }
}

Pagination is not directly applicable to the Cart type fields as defined.

Implements

The Cart type does not implement any interfaces.

Connections

The Cart object connects to multiple related types through its fields:

• customer → Customer
• discounts → [CartDiscount]
• taxLines → [CartTaxLine]
• paymentMethods → [CartPaymentMethod]
• shippingMethods → [CartShippingMethod]
• lines and physicalLines → [CartLineItem]
• shippingAddress and billingAddress → Address

These connections enable rich, nested queries to retrieve comprehensive cart data.

Related Types

• Customer: Represents the customer associated with the cart.
• CartDiscount: Represents discounts applied to the cart.
• CartTaxLine: Represents tax details for the cart.
• CartPaymentMethod: Represents payment options available for the cart.
• CartShippingMethod: Represents shipping options available for the cart.
• CartLineItem: Represents individual items in the cart.
• Address: Represents shipping and billing addresses.

Best Practices

• Selective Field Queries: Request only the fields you need to optimize performance and reduce payload size.
• Use Nested Queries: Leverage nested queries to fetch related data (e.g., customer info, line items) in a single request.
• Cache Results: Cache cart data where appropriate to minimize repeated requests, especially for frequently accessed carts.
• Handle Nullability: Since many fields are optional, always implement null checks in client code to avoid runtime errors.
• Monitor Pricing Fields: Use subtotalPrice, totalNetPrice, totalTax, and totalPrice to accurately display pricing breakdowns.
• Use physicalLines for Fulfillment: When processing shipments, use the physicalLines field to identify shippable items.

Notes

• All monetary fields (subtotalPrice, totalPrice, totalNetPrice, totalTax, paymentFee, shippingPrice) are returned in the customer’s currency.
• The createdAt field follows the RFC 2822 date format.
• The checkoutUrl provides a direct link to the checkout page for the cart.
• The API currently requires no authentication; however, this may change in future versions.
• Since many fields are optional, clients should gracefully handle missing data.
• There are no computed or derived fields explicitly defined on the Cart type beyond the provided fields.
• No field arguments are defined on the Cart type fields.
• Performance can be improved by limiting nested queries to only necessary related objects.
• For carts with a large number of line items, consider paginating or filtering client-side as the API does not provide built-in pagination on the lines field.