docs
Open dashboard

Quickstart

Commerce quickstart

From zero to a paid order in 8 curl calls.

You'll need:

  • A staff PAT with commerce:write scope (mint at Settings → API keys)
  • The {handle} of your commerce account
  • For the storefront half, a Storefront API key (created in step 6)

Set them as env vars first:

export NEVIOS_KEY="nev_pat_..."
export ACCOUNT_HANDLE="my-shop"
export API="https://api.nevios.io/admin/2026-01/$ACCOUNT_HANDLE"

1. Create a market

Markets define currency + locale + country for one regional surface.

curl -X POST "$API/markets.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "cz",
    "name": "Česká republika",
    "currency": "CZK",
    "locale": "cs-CZ",
    "country_code": "CZ",
    "status": "active"
  }'

{ "market": { "id": "308...", "handle": "cz", "currency": "CZK", ... } }

2. Create a product + variant + pricing

# Product
PRODUCT_ID=$(curl -s -X POST "$API/products.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"handle":"trika-bavlna","title":"Bavlněné triko","status":"active"}' \
  | jq -r '.product.id')

# Variant
VARIANT_ID=$(curl -s -X POST "$API/products/$PRODUCT_ID/variants.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"sku":"TRI-001","weight_grams":250}' \
  | jq -r '.variant.id')

# Price (gross 499 CZK with 21% VAT)
curl -X PUT "$API/variants/$VARIANT_ID/pricing.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d "{\"market_id\": $MARKET_ID, \"price_with_tax_cents\": 49900, \"tax_rate_bps\": 2100, \"price_source\": \"gross\"}"

3. Create a location with stock

LOCATION_ID=$(curl -s -X POST "$API/locations.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"handle":"praha-warehouse","name":"Praha","is_default":true}' \
  | jq -r '.location.id')

curl -X PUT "$API/inventory/$VARIANT_ID/$LOCATION_ID/adjust.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"state":"on_hand","delta":50,"type":"received","reason_code":"PO-1"}'

4. Set up shipping

ZONE_ID=$(curl -s -X POST "$API/shipping/zones.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"handle":"cz","name":"CZ","country_codes":["CZ"]}' \
  | jq -r '.shipping_zone.id')

METHOD_ID=$(curl -s -X POST "$API/shipping/methods.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d "{\"handle\":\"ppl-home\",\"name\":\"PPL doručení\",\"zone_id\":$ZONE_ID}" \
  | jq -r '.shipping_method.id')

RATE_ID=$(curl -s -X POST "$API/shipping/methods/$METHOD_ID/rates.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"price_cents":9900,"currency":"CZK"}' \
  | jq -r '.shipping_rate.id')

5. Mint a Storefront API key

SK=$(curl -s -X POST "$API/storefront_keys.json" \
  -H "Authorization: Bearer $NEVIOS_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Storefront","env":"live"}' \
  | jq -r '.storefront_key.key')

# IMPORTANT: this is the only time the key is returned. Store it.

6. Switch to the storefront API

export SF="https://api.nevios.io/storefront/2026-01"

Create a cart, add a line:

CART_TOKEN=$(curl -s -X POST "$SF/carts.json" \
  -H "X-Storefront-Key: $SK" -H "Content-Type: application/json" \
  -d "{\"market_id\": $MARKET_ID}" | jq -r '.cart.token')

curl -X POST "$SF/carts/$CART_TOKEN/lines.json" \
  -H "X-Storefront-Key: $SK" -H "Content-Type: application/json" \
  -d "{\"variant_id\": $VARIANT_ID, \"quantity\": 2}"

7. Walk the checkout state machine

CO_TOKEN=$(curl -s -X POST "$SF/checkouts.json" \
  -H "X-Storefront-Key: $SK" -H "Content-Type: application/json" \
  -d "{\"cart_token\": \"$CART_TOKEN\"}" | jq -r '.checkout.token')

# Address
curl -X PUT "$SF/checkouts/$CO_TOKEN/address.json" \
  -H "X-Storefront-Key: $SK" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","shipping_address":{"address1":"Plzeňská 8","city":"Praha","country_code":"CZ","zip":"15000","first_name":"Anna","last_name":"Nováková"}}'

# Shipping
curl -X PUT "$SF/checkouts/$CO_TOKEN/shipping.json" \
  -H "X-Storefront-Key: $SK" -H "Content-Type: application/json" \
  -d "{\"shipping_method_id\": $METHOD_ID, \"shipping_rate_id\": $RATE_ID}"

# Payment method
curl -X PUT "$SF/checkouts/$CO_TOKEN/payment_method.json" \
  -H "X-Storefront-Key: $SK" -H "Content-Type: application/json" \
  -d '{"payment_method":"cod"}'

# Start + confirm + complete
curl -X POST "$SF/checkouts/$CO_TOKEN/start_payment.json" \
  -H "X-Storefront-Key: $SK" -d '{}'

curl -X POST "$SF/checkouts/$CO_TOKEN/confirm.json" \
  -H "X-Storefront-Key: $SK" -d '{}'

curl -X POST "$SF/checkouts/$CO_TOKEN/complete.json" \
  -H "X-Storefront-Key: $SK" \
  -H "Idempotency-Key: $(uuidgen)" -d '{}'

The complete response includes order_id. Inventory is committed, the customer is created as a guest, and the outbox dispatcher will deliver the order confirmation email within seconds.

What just happened

You created a complete e-shop bottom-up: market, product with VAT pricing, stock, shipping, then walked a buyer through cart → address → shipping → payment → completed order — all via HTTP. The same APIs power the dashboard.

Next steps