Storefront GraphQL API

Build custom sidecarts, upsell flows, and dynamic storefront experiences with the Storefront GraphQL API. Query products, manage carts, apply vouchers, and handle user accounts — all from your theme's JavaScript or any client-side application.

API Endpoint

https://{store}.29next.store/api/graphql/

All requests must be POST with Content-Type: application/json. Replace {store} with your store's subdomain.

Authentication

The Storefront API is available within the context of your storefront on a storefront domain. Requests made from your theme's JavaScript automatically inherit the user's session — no API keys or tokens needed.

Interactive Explorer (GraphiQL)

Every store includes a built-in GraphiQL IDE — an in-browser tool for writing, validating, and testing GraphQL queries directly against your store's schema. Navigate to /api/graphql/ on your store to open it.

GraphiQL lets you:

• Explore the schema — browse all available queries, mutations, types, and their fields using the documentation sidebar
• Build queries visually — use the explorer panel to construct queries by selecting fields, without writing GraphQL by hand
• Test in real-time — run queries and mutations against your store and see the JSON response instantly
• Validate syntax — get inline error highlighting and autocomplete as you type

https://{store}.29next.store/api/graphql/

This is the fastest way to learn what the API offers and prototype queries before adding them to your theme code.

API Reference

Queries

• cart — Retrieve a cart by ID
• me — Get the current authenticated user
• product — Fetch a single product
• products — Query the product catalog

Mutations

• createCart — Create a new cart
• addCartLines — Add line items to a cart
• updateCartLines — Update quantities on existing cart lines
• removeCartLines — Remove line items from a cart
• emptyCart — Remove all items from a cart
• addVoucher — Apply a voucher code to a cart
• removeVoucher — Remove a voucher from a cart
• updateCartAttribution — Set UTM and affiliate attribution on a cart
• updateCartMetadata — Update custom metadata on a cart
• register — Register a new customer account
• tokenAuth — Authenticate and obtain a token
• verifyToken — Verify an authentication token
• updateAccount — Update the current user's account details

Quick start

Fetch the current cart to build a custom sidecart UI:

curl -X POST https://yourstore.29next.store/api/graphql/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Cart($id: ID!) { cart(id: $id) { id numItems totalInclTax currency lines { edges { node { id quantity product { title } linePriceInclTax } } } } }",
    "variables": { "id": "<cart-id>" }
  }'

{
  "data": {
    "cart": {
      "id": "Q2FydE5vZGU6MTIz",
      "numItems": 2,
      "totalInclTax": "59.98",
      "currency": "USD",
      "lines": {
        "edges": [
          {
            "node": {
              "id": "Q2FydExpbmVOb2RlOjE=",
              "quantity": 1,
              "product": { "title": "Premium Supplement" },
              "linePriceInclTax": "29.99"
            }
          }
        ]
      }
    }
  }
}

Common use cases

Custom sidecarts

The most common use of the Storefront API is building custom sidecart experiences. Use cart queries to fetch the current cart state and render a fully custom cart drawer with your own markup, animations, and styling.

Upsells and cross-sells

Add upsell products to the cart dynamically using mutations like addCartLines. Query the product catalog with products to find related items, then present them in your sidecart or on product pages.

mutation AddUpsell($input: AddCartLinesInput!) {
  addCartLines(input: $input) {
    success
    cart {
      numItems
      totalInclTax
    }
  }
}

User accounts

Handle customer registration and authentication directly from your storefront with register, tokenAuth, and updateAccount mutations.

Vouchers and discounts

Apply and remove voucher codes from carts using addVoucher and removeVoucher mutations, enabling custom promo code UIs.