Create a cart and add items with the Storefront API
Build a headless cart: cartCreate with lines and buyer country, cartLinesAdd for more items, and checkoutUrl to send the buyer to checkout.
- API
- Storefront API
- Operations
- cartCreate, cartLinesAdd
- Access scope
- unauthenticated_write_checkouts
- API version
- 2026-10
- Last checked
In short
In a headless storefront, create the cart with the Storefront API’s cartCreate mutation, passing the first lines (merchandiseId is the variant GID) and buyerIdentity.countryCode for local prices. Store the returned cart ID in a cookie and add items with cartLinesAdd, up to 250 lines per request. Send the buyer to cart.checkoutUrl to pay; Shopify’s checkout takes it from there.
How to use it
- Send CreateCart with the first line and the buyer’s country. Keep cart.id, for example in a cookie.
- Send AddToCart with the cart ID and new lines. Line attributes carry things like a gift note to the order.
- Check userErrors and warnings after every call; warnings report problems that didn’t stop the change.
- Link the checkout button to cart.checkoutUrl.
Code
cart-create.graphqlmutation CreateCart($input: CartInput!) {
cartCreate(input: $input) {
cart {
id
checkoutUrl
totalQuantity
cost {
subtotalAmount {
amount
currencyCode
}
}
}
userErrors {
code
field
message
}
warnings {
code
message
target
}
}
}
cart-create.variables.json{
"input": {
"lines": [
{"merchandiseId": "gid://shopify/ProductVariant/1111111111", "quantity": 1}
],
"buyerIdentity": {
"countryCode": "DE"
}
}
}
cart-create.response.json{
"data": {
"cartCreate": {
"cart": {
"id": "gid://shopify/Cart/c1-0000000000000000000000000000000?key=0000000000000000",
"checkoutUrl": "https://your-store.myshopify.com/cart/c/c1-0000000000000000000000000000000?key=0000000000000000",
"totalQuantity": 1,
"cost": {
"subtotalAmount": {
"amount": "49.0",
"currencyCode": "EUR"
}
}
},
"userErrors": [],
"warnings": []
}
}
}
cart-lines-add.graphqlmutation AddToCart($cartId: ID!, $lines: [CartLineInput!]!) {
cartLinesAdd(cartId: $cartId, lines: $lines) {
cart {
id
totalQuantity
lines(first: 20) {
nodes {
id
quantity
merchandise {
... on ProductVariant {
id
title
}
}
}
}
cost {
totalAmount {
amount
currencyCode
}
}
}
userErrors {
code
field
message
}
warnings {
code
message
target
}
}
}
cart-lines-add.variables.json{
"cartId": "gid://shopify/Cart/c1-0000000000000000000000000000000?key=0000000000000000",
"lines": [
{
"merchandiseId": "gid://shopify/ProductVariant/2222222222",
"quantity": 2,
"attributes": [{"key": "Gift note", "value": "Happy birthday!"}]
}
]
}
cart-lines-add.response.json{
"data": {
"cartLinesAdd": {
"cart": {
"id": "gid://shopify/Cart/c1-0000000000000000000000000000000?key=0000000000000000",
"totalQuantity": 3,
"lines": {
"nodes": [
{"id": "gid://shopify/CartLine/00000000-0000-0000-0000-000000000001?cart=c1-0000000000000000000000000000000", "quantity": 1, "merchandise": {"id": "gid://shopify/ProductVariant/1111111111", "title": "M"}},
{"id": "gid://shopify/CartLine/00000000-0000-0000-0000-000000000002?cart=c1-0000000000000000000000000000000", "quantity": 2, "merchandise": {"id": "gid://shopify/ProductVariant/2222222222", "title": "Default Title"}}
]
},
"cost": {
"totalAmount": {
"amount": "119.0",
"currencyCode": "EUR"
}
}
},
"userErrors": [],
"warnings": []
}
}
}
Written by Lintel. MIT license: free to use in your own store and in client work.
Limits and edge cases
- Use a public Storefront access token in the browser or a private one on the server; never an Admin API token.
- buyerIdentity on the cart sets the country context, so prices and availability follow that market.
- To change quantities use cartLinesUpdate, and to remove lines use cartLinesRemove.
- Storefront API Money amounts are Decimal strings such as "49.0".
Questions
- How do I create a cart with the Shopify Storefront API?
- Call cartCreate with lines of merchandiseId (the variant ID) and quantity. The response has the cart ID and the checkoutUrl.
- How do I add a product to an existing cart?
- Call cartLinesAdd with the cart ID and the lines to add, up to 250 per request. The response returns the updated cart.
- How do I show prices in the buyer’s currency in the cart?
- Set buyerIdentity.countryCode when you create the cart, or later with cartBuyerIdentityUpdate. Prices follow the market of that country.
Shopify documentation
- Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
- IDs and store addresses in the examples are placeholders. Replace them with your own.
- Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
- MIT license. Use the code in your own store or in client work.
Need this built, tested and maintained for your store? See API integrations.
