CartQuery

Description

Retrieves detailed information about a cart by its ID. This query allows you to fetch the current state of a cart, including items, addresses, selected shipping and payment methods, and totals.

Endpoint

query cart($cartId: String!, $siteId: Int) {
  cart(cartId: $cartId, siteId: $siteId) {
    # Return fields
  }
}

Arguments

Argument	Type	Required	Description
cartId	String	Yes	The unique identifier of the cart to retrieve. This ID is obtained from createGuestCart or createCustomerCart mutations.
siteId	Int	No	The site ID where the cart is created. Defaults to 1 if not provided.

Return Values

The query returns a CartType object with the following structure:

Field	Type	Description
billing_address	Object	The billing address associated with the cart.
shipping_address	Object	The shipping address associated with the cart.
items	[CartItem]	Array of items in the cart.
selected_shipping_method	Object	The selected shipping method for the cart.
selected_payment_method	Object	The selected payment method for the cart.
totals	Object	Cart totals information.

CartItem Structure

Each item in the items array contains:

Field	Type	Description
id	String	Unique identifier for the cart item.
quantity	Int	Quantity of the product in the cart.
tax_percent	Float	Tax percentage applied to this item.
total_weight	Float	Total weight of this item.
name	String	Product name.
sku	String	Product SKU.
thumbnail	String	URL to the product thumbnail image.
custom	Object	Custom data associated with this item.
price	Money	Base price of the product.
price_tax_amount	Money	Tax amount for a single unit.
price_including_tax	Money	Price including tax for a single unit.
price_excluding_tax	Money	Price excluding tax for a single unit.
row_total	Money	Total price for this item (quantity × price).
row_total_tax_amount	Money	Total tax amount for this item.
row_total_including_tax	Money	Total price including tax for this item.
row_total_excluding_tax	Money	Total price excluding tax for this item.

Money Structure

Price fields use the Money structure:

Field	Type	Description
value	Float	The numerical value.
currency	String	The currency code (e.g., "USD").

Address Structure

The billing_address and shipping_address fields contain:

Field	Type	Description
firstname	String	First name.
lastname	String	Last name.
company	String	Company name.
street	String	Street address.
city	String	City.
region	String	Region or state.
postcode	String	Postal or ZIP code.
country_id	String	Country code.
telephone	String	Phone number.
email	String	Email address.

Totals Structure

The totals field contains:

Field	Type	Description
grand_total	Money	The total amount for the cart including tax, shipping, and discounts.
subtotal	Money	The subtotal amount for the cart (sum of all items before tax, shipping, and discounts).
tax_amount	Money	The total tax amount for the cart.
shipping_amount	Money	The shipping amount for the cart.
discount_amount	Money	The discount amount applied to the cart.

Usage Example

query {
  cart(cartId: "abc123") {
    items {
      id
      quantity
      name
      sku
      price {
        value
        currency
      }
      row_total {
        value
        currency
      }
    }
    billing_address {
      firstname
      lastname
      street
      city
      postcode
      country_id
      telephone
      email
    }
    shipping_address {
      firstname
      lastname
      street
      city
      postcode
      country_id
      telephone
    }
    selected_shipping_method {
      carrier_code
      method_code
      carrier_title
      method_title
      amount {
        value
        currency
      }
    }
    selected_payment_method {
      code
      title
    }
    totals {
      grand_total {
        value
        currency
      }
      subtotal {
        value
        currency
      }
      tax_amount {
        value
        currency
      }
      shipping_amount {
        value
        currency
      }
      discount_amount {
        value
        currency
      }
    }
  }
}

Example Response

{
  "data": {
    "cart": {
      "items": [
        {
          "id": "123",
          "quantity": 2,
          "name": "Sample Product",
          "sku": "product-123",
          "price": {
            "value": 19.99,
            "currency": "USD"
          },
          "row_total": {
            "value": 39.98,
            "currency": "USD"
          }
        }
      ],
      "billing_address": {
        "firstname": "John",
        "lastname": "Doe",
        "street": "123 Main St",
        "city": "Anytown",
        "postcode": "12345",
        "country_id": "US",
        "telephone": "555-123-4567",
        "email": "john.doe@example.com"
      },
      "shipping_address": {
        "firstname": "John",
        "lastname": "Doe",
        "street": "123 Main St",
        "city": "Anytown",
        "postcode": "12345",
        "country_id": "US",
        "telephone": "555-123-4567"
      },
      "selected_shipping_method": {
        "carrier_code": "flatrate",
        "method_code": "flatrate",
        "carrier_title": "Flat Rate",
        "method_title": "Fixed",
        "amount": {
          "value": 5.00,
          "currency": "USD"
        }
      },
      "selected_payment_method": {
        "code": "checkmo",
        "title": "Check / Money Order"
      },
      "totals": {
        "grand_total": {
          "value": 44.98,
          "currency": "USD"
        },
        "subtotal": {
          "value": 39.98,
          "currency": "USD"
        },
        "tax_amount": {
          "value": 0,
          "currency": "USD"
        },
        "shipping_amount": {
          "value": 5.00,
          "currency": "USD"
        },
        "discount_amount": {
          "value": 0,
          "currency": "USD"
        }
      }
    }
  }
}

Notes

• If the cart has been converted to an order, this query will throw an error with the message "The cart has already been converted to an order. Register a new cart to continue."
• The cart must exist for the query to succeed. If the cart ID is invalid, an error will be returned.
• This query will return the most up-to-date information about the cart, including any changes made by other mutations.
• The reload parameter is set to true internally, which means the cart data is always refreshed from the database before being returned.