Build a storefront

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

Amounts as strings. The decimal fields of products, cart, checkout, and orders (price, unit_price, subtotal, total…) arrive as strings ("1199.00"). Convert them before doing math: in JavaScript "10.00" + "5.00" concatenates instead of adding. For money, use a decimal library or work in cents.

1. Catalog & search

# 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"

The min_price and max_price filters and the sort=price / sort=-price ordering work on the effective price (active sale and special price), and meta.total always matches the filtered rows. in_stock=true keeps only products with a purchasable variant.
In the list, sale_price is the variant’s active sale or the special price, whichever is lower; null when no discount is active.

The product detail (GET /products/{slug}) has two new fields:

Field	Meaning
`special_price`	special price active for a guest, at product level. Show it as the discounted price when it’s below the variant’s price
`stock_status_name`	availability text chosen by the store (for example “Coming soon”), already in the requested language: show it when the variant is out of stock

{
  "data": {
    "slug": "iphone-17-pro-256gb",
    "special_price": "1149.00",
    "stock_status_name": "Coming soon",
    "variants": [
      {
        "sku": "IPH17P-256-NERO",
        "price": "1249.00",
        "compare_at_price": "1349.00",
        "sale_price": null,
        "stock": 0,
        "track_inventory": true,
        "allow_backorder": false
      }
    ]
  }
}

On variants, sale_price is null outside the sale window (sale_start–sale_end). A variant with track_inventory: false can be bought even at zero stock.

2. Cart

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

# 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 (lines, applied prices, store rules)
curl "$BASE/api/v1/cart"

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.

# 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}'

When the guest signs in, their cart merges into the account’s cart on the first authenticated cart call, or checkout, that still carries the guest token (X-Cart-Token or the cx_cart cookie):

the same item adds up, but never beyond the available stock;
items no longer for sale stay behind;
the guest cart is then deleted, and the same token never merges twice.

What to do in the client:

keep sending X-Cart-Token after the login;
reload the cart right after signing in (password, social login or registration), so the badge and the drawer show the merged items;
once the cart response has user_id set, stop using the guest token;
on sign-out, clear the account’s cart from the screen.

The price to show is `unit_price`

Each line carries the price actually applied, which already accounts for sale, special price, quantity discount, and the customer’s group: unit_price, with line_total = unit_price × quantity. Show that one. variant.price and variant.sale_price are list prices and must not be used for lines and totals.

{
  "data": {
    "session_token": "kJ8x...",
    "items": [
      {
        "id": "e5f6a7b8-0000-4000-8000-abcdefabcdef",
        "variant_id": "11112222-3333-4444-8555-666677778888",
        "quantity": 2,
        "unit_price": "1149.00",
        "line_total": "2298.00",
        "variant": { "sku": "IPH17P-256-NERO", "price": "1249.00", "sale_price": null }
      }
    ],
    "subtotal": "2298.00",
    "item_count": 2,
    "min_order_total": "20.00",
    "guest_checkout_enabled": true
  },
  "meta": null,
  "error": null,
  "error_code": null
}

Store rules

The cart exposes the rules the checkout enforces, so you can show them before payment:

min_order_total: minimum order on the subtotal (zero = no minimum). Below the threshold, show how much is missing and disable the payment button.
guest_checkout_enabled: with false the store accepts orders only from registered customers. Ask for login or sign-up before checkout.

3. Checkout & payment

Always take the payment methods from the public list: the checkout accepts only those. Each method is a stable code (stripe, paypal, pokpay, paysera, bank_transfer, cod) to translate in the client.

# payment methods active in the store
curl "$BASE/api/v1/settings/payment-methods"
# create the order (guest): always send a payment_method taken from the list
curl -X POST "$BASE/api/v1/checkout" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "X-Cart-Token: <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "customer@example.com",
    "payment_method": "stripe",
    "coupon_code": "SUMMER10",
    "voucher_code": "GIFT50",
    "locale": "en",
    "shipping_address": {
      "first_name": "Mario", "last_name": "Rossi",
      "address_line1": "Via Roma 12", "city": "Milano",
      "postal_code": "20121", "country": "IT", "phone": "+39 333 1234567"
    }
  }'

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. An online order that was never paid can be reopened with POST /orders/{order_id}/pay (“Pay now”): same response as the checkout, same order. See the API Reference for the exact schema of POST /checkout.

Store rule errors

`error_code`	HTTP	When	`data`
`checkout.min_order_not_met`	422	subtotal below the minimum order	`min_order_total`, `subtotal`, `currency`
`checkout.login_required`	401	the store doesn’t accept guest orders	—
`checkout.payment_method_disabled`	422	method switched off by the store (even when omitted: the default is `stripe`)	`payment_method`

A coupon’s discount never exceeds the subtotal, and a “free shipping” coupon zeroes the shipping cost.

Gift voucher

The customer enters the voucher code and you send it in voucher_code. The balance pays the total after the coupon, shipping included.

The balance is reserved when the order is created and becomes final on payment: two checkouts can’t spend the same balance.
The balance goes back to the voucher when the payment attempt is really closed (payment canceled, attempt replaced by a new checkout, order canceled by the store) and, for a paid order, with a full refund or a cancellation. A declined card does not release the voucher, because the same payment can be retried.
If the voucher covers the whole total, the response has payment_method: "voucher" and no gateway data: the order is already paid, go to the confirmation page.
The response carries voucher_code, voucher_amount (amount used), and voucher_remaining (balance left, to show to the customer).
A voucher can’t pay for a subscription.

`error_code`	HTTP	Meaning
`voucher.not_found`	404	unknown code
`voucher.inactive`	422	voucher deactivated
`voucher.reserved`	422	the balance is held by another online order still awaiting payment
`voucher.exhausted`	422	voucher already fully spent
`voucher.not_with_subscription`	422	the voucher can’t be used with `subscribe_recurring_id`
`voucher.insufficient_balance`	409	”Pay now” only: the balance was spent elsewhere in the meantime

4. Orders & tracking

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

The history (history) the customer sees is filtered:

it contains only status changes (event_type: "status_change") and public notes (event_type: "note"); payments, refunds, shipments, and emails stay with the staff;
a status row written by the system has comment: null: translate the status in the client. The comment stays only when a staff member wrote it and made it public;
a note has status: null.

{
  "history": [
    { "event_type": "status_change", "status": "processing", "comment": null, "created_at": "2026-10-04T09:31:12Z" },
    { "event_type": "status_change", "status": "shipped", "comment": "Expected delivery on Friday", "created_at": "2026-10-05T08:15:00Z" },
    { "event_type": "note", "status": null, "comment": "We added a free sample", "created_at": "2026-10-05T08:20:00Z" }
  ]
}

payment_status can also be partially_refunded; payment_method can be voucher.

5. Subscriptions

A product can have recurring plans (recurrings in the product detail). The customer subscribes at checkout with subscribe_recurring_id (login and payment_method: "stripe" are required).

At purchase the customer pays the product price; renewals are charged at the plan price (price).
The “trial” only moves the first renewal: it comes after trial_length units of trial_frequency instead of after one interval. trial_price is not applied.
billing_interval says every how many frequency units it renews; billing_charges is the total number of charges, purchase included (0 = until canceled).

In GET /account/subscriptions the status can be active, trialing, past_due, paused, canceled, or completed: finished, every installment charged and next_billing_date: null. On a completed subscription hide the cancel button: POST /account/subscriptions/{id}/cancel answers 409 subscription.already_completed.

Quick tip: the full list of parameters, request bodies, and responses is in the API Reference, generated from the live OpenAPI schema — so it’s always aligned with production.

Campaigns

A campaign link looks like https://<store>/…?cmp=<code>. When the storefront finds the cmp parameter, it calls once per browser:

curl -X POST "$BASE/api/v1/marketing/track" \
  -H "X-Vellaro-Key: cx_pk_live_<slug>_..." \
  -H "Content-Type: application/json" \
  -d '{"code":"AUTUMN26"}'
# → { "data": { "counted": true }, ... }

The same visit counts once every 30 minutes (counted: false for the following ones) and an unknown code answers 200 with counted: false. Limit: 30 requests per minute per IP.

Appearance & configuration

GET /settings/store-info — name, contacts, social, appearance (logo, colors) to brand your frontend like the store. It also contains:
- catalog.items_per_page (products per page, null = your choice) and catalog.default_sort (default category ordering, already in the GET /products?sort= syntax, or null);
- seo.meta_title_default and seo.meta_description_default: title and description for pages without their own meta (empty string = not set).
GET /banners, GET /information/<slug> — CMS content and hero.
GET /languages, GET /currencies — for language/currency selectors.

Get started

Guides

AI & MCP

Build a storefront

1. Catalog & search

2. Cart

The price to show is `unit_price`

Store rules

3. Checkout & payment

Store rule errors

Gift voucher

4. Orders & tracking

5. Subscriptions

Campaigns

Appearance & configuration

1. Catalog & search

2. Cart

The cart at sign-in

The price to show is unit_price

Store rules

3. Checkout & payment

Store rule errors

Gift voucher

4. Orders & tracking

5. Subscriptions

Campaigns

Appearance & configuration

The price to show is `unit_price`