loading...
CartQL

Manage Shopping Carts with GraphQL

notrab profile image Jamie Barton ・8 min read

CartQL is a GraphQL Shopping Cart API designed to work with your existing frontend or backend.

  • Built for the Jamstack - No more writing custom business logic to handle cart and checkout. Works with Apollo Client, URQL, fetch, and more.

  • Flexible cart items - Store any type of data on cart and cart items with the CartQL Mutations API

  • No replatforming - CartQL was built to handle custom cart items for SKUs, promotions, shipping, and so much more.

  • Bring your own inventory - Whether you're storing products in the filesystem, or in another API, such as CMS, it works with CartQL.

  • Bring your own frontend, or backend - No more learning new client-side libraries for each framework to manage cart state. Work with what you already use, or stitch it with other GraphQL APIs.


Manage cart items, checkout and pay for orders with a simple declarative GraphQL API.

Try it out!

The API is completely open, and free to use. See some of the common mutations users use when building their commerce experience.

Fetch a new or existing Cart

query {
  cart(
    id: "ck5r8d5b500003f5o2aif0v2b",
    currency: {
      code: GBP
    }
  ) {
    ...CartWithItems
  }
}

fragment CartWithItems on Cart {
  ...CartInfo
  items {
    ...ItemInfo
  }
}

fragment CartInfo on Cart {
  id
  email
  isEmpty
  abandoned
  totalItems
  totalUniqueItems
  currency {
    code
    symbol
  }
  subTotal {
    amount
    formatted
  }
  shippingTotal {
    amount
    formatted
  }
  taxTotal {
    amount
    formatted
  }
  grandTotal {
    amount
    formatted
  }
  attributes {
    key
    value
  }
  notes
  createdAt
  updatedAt
}

fragment ItemInfo on CartItem {
  id
  name
  description
  images
  quantity
  attributes {
    key
    value
  }
  unitTotal {
    amount
    formatted
  }
  lineTotal {
    amount
    formatted
  }
  createdAt
  updatedAt
}

Add to Cart

Items by default are of type SKU, but you can add SHIPPING, and TAX, which modify the subTotal, grandTotal values.

mutation {
  addItem(
    input: {
      cartId: "ck5r8d5b500003f5o2aif0v2b",
      id: "5e3293a3462051",
      name: "Full Logo Tee",
      description: "Purple Triblend / L",
      images: ["full-logo-tee.png"],
      price: 2000
    }
  ) {
    id
    isEmpty
    abandoned
    totalItems
    totalUniqueItems
    subTotal {
      formatted
    }
  }
}

Update Cart Item

Update any of the item properties using the updateItem GraphQL mutation.

mutation {
  updateItem(
    input: {
      cartId: "ck5r8d5b500003f5o2aif0v2b",
      id: "5e3293a3462051",
      price: 2500
      quantity: 2
    }
  ) {
    id
    isEmpty
    abandoned
    totalItems
    totalUniqueItems
    subTotal {
      formatted
    }
  }
}

 Remove Cart Item

mutation {
  removeItem(
    input: {
      cartId: "ck5r8d5b500003f5o2aif0v2b",
      id: "5e3293a3462051"
    }
  ) {
    id
    isEmpty
    abandoned
    totalItems
    totalUniqueItems
    subTotal {
      formatted
    }
  }
}

Custom Item Data

Some items have more than just a name, description, and price, but attributes such as engraving, personalized notes, and more.

You can use the attributes array to store custom data.

mutation {
  updateItem(
    input: {
      cartId: "ck5r8d5b500003f5o2aif0v2b",
      id: "5e3293a3462051",
      attributes: [
        {
          key: "Engraving",
          value: "Jamie"
        }
      ]
    }
  ) {
    id
    email
    attributes {
      key
      value
    }
  }
}

Currency Formatting

No matter the location of your users, you can format the cart based on their currency. The updateCart GraphQL mutation accepts properties for currency, which include things such as the code, symbol, thousandsSeparator, and more.

CartQL will automatically figure out the symbol, separator, and more, based on the code you give it.

Try swapping out GBP in the example below with EUR, TRY, or USD, and see all money meta in the cart change.

mutation {
  updateCart(
    input: {
      id: "ck5r8d5b500003f5o2aif0v2b",
      currency: {
        code: GBP
      }
    }
  ) {
    id
    currency {
      code
      symbol
      thousandsSeparator
      decimalSeparator
      decimalDigits
    }
  }
}

Checkout

Are you ready to checkout your cart?

CartQL provides a checkout mutation that you can use on the frontend to help capture customer addresses, emails, and notes.

mutation {
  checkout(
    input: {
      cartId: "ck5r8d5b500003f5o2aif0v2b",
      email: "jamie@cartql.com",
      shipping: {
        name: "Jamie Barton",
        line1: "123 Cart Lane",
        city: "Newcastle upon Tyne",
        postalCode: "NE14 CQL",
        country: "England"
      },
      billing: { # Optional
        name: "Jamie Barton",
        line1: "123 Cart Lane",
        city: "Newcastle upon Tyne",
        postalCode: "NE14 CQL",
        country: "England"
      }
    }
  ) {
    id
    grandTotal {
      formatted
    }
  }
}

🔥 With the paid addition of CartQL (launching soon) you can attach webhooks to all cart mutations, including checkout! 🔥

... and lots more!

There's mutations to setItems, incrementItemQuantity, decrementItemQuantity, emptyCart, deleteCart, and more on the way!

Interested?

The Gatsby CartQL Starter is a great place to get going! Built with Apollo Client 3, and a local inventory, this shows the full power of CartQL 🚀

Discussion

pic
Editor guide