> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vellaro.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a storefront

> Catalog → cart → checkout → order, with the Storefront API.

This guide walks through the core storefront flow. All endpoints live under
`/api/v1` and use the [publishable key](/en/authentication) (or the store domain).

## 1. Catalog & search

```bash theme={null}
# list products with filters
curl "$BASE/api/v1/products?category_id=<id>&min_price=500&sort=-created_at&page=1&page_size=24"
# detail by slug
curl "$BASE/api/v1/products/<slug>?lang=it"
# full-text search with facets
curl "$BASE/api/v1/search?q=iphone&page=1"
# categories (tree), brands
curl "$BASE/api/v1/categories?tree=true"
```

## 2. Cart

The cart works for guests (with a session id/token) and for logged-in customers.

```bash theme={null}
# create/update cart, add a variant
curl -X POST "$BASE/api/v1/cart/items" -H "Content-Type: application/json" \
  -d '{"variant_id":"<id>","quantity":1}'
# read the cart (totals, estimated shipping)
curl "$BASE/api/v1/cart"
```

<Note>
  **Cross-origin / headless cart.** The guest cart is keyed by a session token, returned in the
  response's `session_token` field. If your storefront runs on a different origin than the API
  (e.g. `xxxx.com` → `api.vellaro.io`), the `cx_cart` cookie (`SameSite=Lax`) is not sent
  cross-site: **store `session_token` client-side** (e.g. `localStorage`) and send it back on
  **every** cart call and at checkout as the **`X-Cart-Token`** header. The cart then persists
  anywhere and is **restored** on the shopper's return (7-day TTL). Same-origin? The cookie is
  enough and the header is optional.
</Note>

```bash theme={null}
# the response contains { "data": { "session_token": "…", "items": [...] } }
# → store session_token and send it back on every cart call + checkout:
curl -X POST "$BASE/api/v1/cart/items" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "X-Cart-Token: <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"variant_id":"<id>","quantity":1}'
```

## 3. Checkout & payment

```bash theme={null}
# payment methods available for the store
curl "$BASE/api/v1/settings/payment-methods"
# create the order
curl -X POST "$BASE/api/v1/checkout" -H "Content-Type: application/json" \
  -d '{ "email":"cliente@example.com", "shipping_address": { ... }, "payment_method":"stripe" }'
```

The checkout response indicates the **payment flow** (Stripe, PayPal, PokPay, Paysera,
cash on delivery, bank transfer): some return a `client_secret`/redirect to complete
client-side, others confirm immediately. See the [API Reference](/en/api-reference) for the
exact schema of `POST /checkout`.

## 4. Orders & tracking

```bash theme={null}
# customer's orders (authenticated)
curl "$BASE/api/v1/orders" -H "Authorization: Bearer $TOKEN"
# tracking for an order
curl "$BASE/api/v1/orders/<id>"
```

<Check>
  Quick tip: the full list of parameters, request bodies, and responses is in the
  [API Reference](/en/api-reference), generated from the **live** OpenAPI schema — so it's always
  aligned with production.
</Check>

## Appearance & configuration

* `GET /settings/store-info` — name, contacts, social, **appearance** (logo, colors) to
  brand your frontend like the store.
* `GET /banners`, `GET /information/<slug>` — CMS content and hero.
* `GET /languages`, `GET /currencies` — for language/currency selectors.