Skip to content
Cartly Docs
Log in
Getting started

Connect your first storefront

Cartly's client API is designed to be called by your storefront server. Resolve the shop from its host, keep secrets server-side, and render the experience in the client you already own.

Open API reference

The mental model

Every request is scoped to a published storefront using X-Storefront-Host. Your server makes the request to Cartly's GraphQL endpoint, then passes only the data your UI needs to the browser.

01

Resolve the store

02

Query the data

03

Render your UI

Request context

Send the storefront host on every request. Carts add a secret cart token, customer sessions add a customer token, and checkout requires an idempotency key.

HTTP headerscopy
Content-Type: application/json
Accept: application/graphql-response+json
X-Storefront-Host: shop.example.com

# only when the operation needs them
X-Cart-Token: cart_secret
X-Customer-Token: customer_secret
Idempotency-Key: checkout_attempt_01

Your first query

Start with a small product query. Pagination is cursor-based, so you can progressively load a collection without guessing offsets.

GraphQLcopy
query StorefrontProducts($page: PageInput) {
  storefrontProducts(page: $page) {
    items {
      id
      slug
      title
      media { url altText kind }
      variants { id price currency inStock }
    }
    pageInfo { nextCursor hasMore limit }
  }
}

Next steps

Add category navigation and product detail pages.
Create a cart on the server and persist its token securely.
Never expose cart or customer tokens to browser scripts.
NextStorefront catalog