Get or Create Cart

Carts are public, shared by all, and retrievable by id. Carts contain all of the basic meta you need to build a cart + checkout, including totals with tax, shipping, and cart item line, and sub totals.

Carts persist for 14 days. Make sure you update the cart if to keep it alive if you are sending customers recovery/abandoned emails.

Query

cart(id: ID!, currency: CurrencyInput): Cart!

ArgumentsTypeDescription
idID!The id of the cart you want to fetch
currencyCurrencyInputThe cart currency properties

The cart query will always return the Cart object.

ID!

You must provide an id for the cart you want to fetch. If no cart exists, CartQL will create one for you with the id provided.

Carts are public. Make sure to set a unique complex cart id.

{
  cart(id: "ck5r8d5b500003f5o2aif0v2b") {
    id
    isEmpty
    totalItems
    items {
      id
    }
  }
}
{
  "data": {
    "cart": {
      "id": "ck5r8d5b500003f5o2aif0v2b",
      "isEmpty": true,
      "totalItems": 0,
      "items": []
    }
  }
}

CurrencyInput

When fetching a cart that does not exist, the values you provide here will set the cart currency.

FieldTypeDefault value
codeCurrencyCodeUSD
symbolString$
thousandsSeparatorString,
decimalSeparatorString.
decimalDigitsInt2
query {
  cart(id: "ck5r8d5b500003f5o2aif0v2b", currency: { code: GBP }) {
    id
    currency {
      code
      symbol
    }
  }
}
{
  "data": {
    "cart": {
      "id": "ck5r8d5b500003f5o2aif0v2b",
      "currency": {
        "code": "GBP",
        "symbol": "£"
      }
    }
  }
}

Learn more about managing currencies.

The Cart object

Carts are the core concept of CartQL. Bring your own PIM, and use CartQL to manage cart metadata.

FieldTypeDescription
idID!A custom unique identifer for the cart provided by you.
currencyCurrency!The current currency details of the cart.
emailStringThe customer email who the cart belongs to.
totalItemsIntThe number of total items in the cart.
totalUniqueItemsIntThe number of total unique items in the cart.
items[CartItem!]!The items in the cart.
subTotalMoney!Sum of all SKU items, excluding discounts, taxes, shipping, including the raw/formatted amounts and currency details.
shippingTotalMoney!The cart total for all items with type SHIPPING, including the raw/formatted amounts and currency details.
taxTotalMoney!The cart total for all items with type TAX, including the raw/formatted amounts and currency details.
grandTotalMoney!The grand total for all items, including shipping, including the raw/formatted amounts and currency details.
abandonedBooleanA simple helper method to check if the cart hasn't been updated in the last 2 hours.
attributes[CustomCartAttribute!]!Custom key/value attributes array for the cart.
notesStringAny notes related to the cart/checkout.
createdAtDate!The date and time the cart was created.
updatedAtDate!The date and time the cart was created.

CustomCartAttribute

It is often useful to save user specific state in the cart for UI, or checkout purposes.

FieldTypeDescription
keyString!Custom attributes must have a key.
valueStringThe value of your custom attribute.

[CartItem!]!

Each CartItem is made up of the values you provide when adding to cart. These items are provided by you, and only an id, and price is required for items to be added.

There are also a handful of other fields you can define for capturing more details about your items.

FieldTypeDescription
idID!A custom unique identifier for the item provided by you.
nameStringThe items name.
descriptionStringThe items description.
typeCartItemTypeThe type of item this is, SKU, TAX, or SHIPPING.
images[String]An array of image URLs for the item.
unitTotalMoney!The unit total for the individual item.
lineTotalMoney!The line total (quantity * price).
quantityInt!The number of items.
attributes[CustomCartAttribute!]!Custom key/value attributes array for the item.
createdAtDate!The date and time the item was added.
updatedAtDate!The date and time the item was last updated.