Skip to content
Cartly Docs
Log in
API reference

GraphQL API

A typed, client-facing GraphQL surface for storefront data and shopper journeys. The API is intentionally narrow: it exposes what a storefront needs, not internal operations.

Open API reference

Endpoint

Send POST requests to the Cartly GraphQL endpoint from your storefront server. The exact API origin comes from your environment configuration.

POSTcopy
POST /api/graphql
Content-Type: application/json

{ "query": "...", "variables": {} }

Headers

X-Storefront-Host

Required on every client request. Resolves the published storefront.

X-Cart-Token

Required for cart and checkout operations. Keep it server-side.

X-Customer-Token

Required for signed-in shopper operations.

Idempotency-Key

Required for checkout. Reuse it for safe retries.

Operations

Catalog

storefrontProducts, storefrontProduct, storefrontCategories

Commerce

createCart, cart, setCartItem, removeCartItem, checkout

Store experience

storefrontShippingMethods, storefrontPaymentMethods, storefrontServiceCoverage

Customer

registerCustomer, customerLogin, customerAccount, customerOrders

Errors and retries

GraphQL errors include a stable code, message, optional path, and request id. Treat validation and authentication errors as user-actionable; retry only network and timeout failures.

Log the request id with your server error so support can trace the request without exposing tokens.
PreviousStorefrontsNextAuthentication