Vittles API

Authentication

Every request except GET /openapi.json carries Authorization: Bearer <key>. Keys are issued by the venue owner in Vittles under Channels → API. There is no CORS: secret keys are for your server, not the browser.

Authorization: Bearer sk_live_…
Content-Type: application/json
Accept-Language: en

A secret key that arrives with an Origin header is rejected with 403 secret_key_in_browser— browsers add that header to every request and servers never do. Call the API from your route handler, API route, WordPress hook or cron, and let your page talk to your server.

Keys & scopes

sk_live_… is a secret key for your server (scopes chosen by the owner, menu:read, orders:write and inquiries:write by default). sk_test_… is the same with test mode: nothing is stored, the counter stays silent. pk_live_… is the kiosk's public key — it may only be used by the Vittles kiosk page. The venue is always derived from the key, never from the request.

Scopes: menu:read, orders:quote, orders:write, orders:read, inquiries:write. A secret key gets the scopes the owner chose (menu:read, orders:write and inquiries:write by default; orders:write includes orders:quote and orders:read); a kiosk key always has menu:read and orders:write. A call outside the key's scopes is 403 insufficient_scope. Rotating a key keeps the old one valid for 24 hours so you can switch without downtime. Reserved for later, not implemented: menu:write and settings:* scopes, and server-sent events. They will appear here first.

Scopes say what a key may do: menu:read (GET /menu, POST /offers/seen), orders:quote (POST /orders/quote and POST /addresses/suggest, nothing is written), orders:write (POST /orders; it includes orders:quote and orders:read), orders:read (GET /orders/{id} for the orders of the key's own channel: a secret key reads orders created with secret keys, the kiosk key the kiosk's) and inquiries:write (POST /inquiries). The owner can change a secret key's scopes at any time in Channels → API; the kiosk key always has menu:read and orders:write. A call outside the scopes is 403 insufficient_scope.

The owner decides per channel what the menu shows and what it allows (Vittles → Channels): hide sold-out items or show them as sold out, hide items sold only in the restaurant, include or exclude categories (for example no drinks), switch the daily menu and photos off, set the channel to browse only, and narrow the fulfillment types and payment methods. A secret key and the kiosk key each follow their channel's rules, and a single key can carry its own content rules on top. GET /menu returns the menu after these rules; POST /orders and POST /orders/quote reject what the rules hide or forbid with the usual codes and details.reason: "channel" (item_not_orderable, ordering_disabled, fulfillment_not_offered, payment_method_not_offered). Test keys follow the same rules. Allergens and prices are always sent.

Keys and the widget are part of the Ultra plan; on a lower plan the API answers 403 plan_required (test keys included) and the embed shows a notice linking to the hosted menu. Keys are kept, not deleted — they answer again as soon as the plan is restored.

Test mode

A sk_test_ key runs POST /orders as a dry run through the same pricing and validation as a live order, inside a transaction that is rolled back. The response is a real-looking order with id: "test_…", number: 0 and test: true. GET /orders/test_… answers from the id's age: new → accepted → in_kitchen → ready (3 min) → closed (5 min, is_final). A test key cannot read live orders. GET /menu returns the real menu.

Menu

GET /menu lists the menu as the owner set it for your channel, by default the whole menu, including what the venue sells only in the restaurant. Offer ordering only for items with orderable: true; show an item with orderable: false and available: true without an add button, as "in the restaurant only" — once at the category heading when the category's own orderable is false. POST /orders and POST /orders/quote with such an item answer 422 item_not_orderable with details.item_id.

curl https://vittles.eu/api/v1/menu \
  -H "Authorization: Bearer $VITTLES_API_KEY" \
  -H "Accept-Language: en"

// Server-side only (route handler, API route, cron). Never in the browser.
const res = await fetch("https://vittles.eu/api/v1/menu", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VITTLES_API_KEY}`,
  },
});
const body = await res.json();
if (!res.ok) {
  // body.error.code is stable; body.error.message is for your log
  throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
}

// wp-config.php: define('VITTLES_API_KEY', 'sk_live_…'); — never in a theme option or in JavaScript.
$response = wp_remote_request('https://vittles.eu/api/v1/menu', [
    'method'  => 'GET',
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . VITTLES_API_KEY,
    ],
]);
if (is_wp_error($response)) { error_log('Vittles: ' . $response->get_error_message()); return; }
$body = json_decode(wp_remote_retrieve_body($response), true);
if (wp_remote_retrieve_response_code($response) >= 400) {
    error_log('Vittles ' . $body['error']['code'] . ': ' . $body['error']['message']);
}

Daily menu

daily in GET /menu is today's daily menu (Europe/Bratislava business day), or null when nothing is published for today. It is not a category: show it as its own section above the menu while state is upcoming (no add button — ordering starts at orders_from) or open, and hide it when it is ended. The window is half-open: an order sent at orders_until is already 422 daily_menu_closed, on every channel — the server decides, not your clock. The state changes at orders_from and orders_until without any edit, so the ETag changes too; poll GET /menu (a 304 is cheap) or refetch at those instants. Order a dish by its id as item_id, like any item. A dish with includes_soup: true comes with a soup in its price: when soup_choice_required is true (two or more soups are available), send the chosen soup's id as soup_id on the same line (otherwise 422 daily_soup_required, details.reason: "choose") — offer only soups with available: true; with one available soup the server picks it and the quote shows it in items[].soup_id, with none the dish goes without soup. A soup with orderable_alone: true can also be its own line (item_id) while its orderable is true; one with orderable_alone: false alone is 422 daily_soup_not_sold_alone. Offer the add button only for orderable: true — the same rule as regular items plus the window. When an order fails with daily_menu_closed, refresh the menu and drop the daily lines from the cart.

Variants and amounts

An item can come in sizes or options with their own price — Kofola 0.3 l for 1.80 and 0.5 l for 2.50 is ONE item with two variants. Each variant has an id, an optional name (the venue's own label, large), an amount ({ "value": 0.5, "unit": "l" }; units g, kg, ml, cl, dl, l, pcs, portion), its price_cents, available and a ready-to-show label in the response language. The item's price_cents is then the lowest variant price — show it as "from …" and let the guest pick. Send the pick as variant_id next to item_id on the order line; two sizes of one item are two lines. An item with variants and no variant_id is 422 variant_required; a variant_id the item does not have (deleted since you read the menu, another item's, or any on an item without variants) is 422 variant_invalid — refresh GET /menu; a sold-out variant (available: false) is 422 item_unavailable with the full name in details.item_name (Kofola 0,5 l). All three carry details.item_name. The quote and the order status show the chosen variant as items[].variant, and the line's name ends with it. Items with variants: [] are ordered exactly as before. amount is also on items and daily dishes without variants: the structured form of portion (which stays the text to show), or null when the venue wrote none or free text.

// GET /menu — categories[].items[]
{
  "id": "5b0c7a52-1d3e-4f6a-8b9c-0d1e2f3a4b5c",
  "name": "Kofola",
  "portion": null,
  "amount": null,
  "price_cents": 180,
  "variants": [
    { "id": "9e8d7c6b-5a49-4382-a1b0-c9d8e7f6a5b4", "name": null,
      "amount": { "value": 0.3, "unit": "l" }, "price_cents": 180, "available": true, "label": "0.3 l" },
    { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": null,
      "amount": { "value": 0.5, "unit": "l" }, "price_cents": 250, "available": true, "label": "0.5 l" }
  ]
}

// POST /orders (and /orders/quote) — items[]
{ "item_id": "5b0c7a52-1d3e-4f6a-8b9c-0d1e2f3a4b5c", "variant_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "quantity": 2 }

// POST /orders/quote — items[] (GET /orders/{id} has the same "variant")
{ "item_id": "5b0c7a52-1d3e-4f6a-8b9c-0d1e2f3a4b5c", "name": "Kofola 0,5 l", "quantity": 2,
  "unit_price_cents": 250, "line_total_cents": 500, …,
  "variant": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": null,
               "amount": { "value": 0.5, "unit": "l" }, "price_cents": 250, "label": "0,5 l" } }

Dish tags

Each item carries tags: the venue's labels for the dish as keys, at most 4, in a fixed order (new, spicy, very_spicy, vegetarian, vegan, seasonal, homemade, kids). Show them in your own words and let guests filter by them. spicy and very_spicy never come together. Tags are content: a change bumps menu_version like any other menu edit. More keys may be added later, so ignore keys you do not know. [] = no tags.

Photos

Categories and items carry photos: up to 6 photos in the owner's order, each { url, width, height, alt } (width and height are null for photos linked from another website, alt is the owner's description in the Accept-Language language, otherwise in the other one, otherwise null). The first photo is the main one and always equals photo_url: show it wherever there is room for one, and the rest as a gallery the guest can swipe through. venue.theme.photos.slideshow describes what the hosted menu does with galleries (mode manual or auto, effect fade, slide or slow_zoom, interval_ms 3000 to 8000); it never tells you what to do, and an unknown mode should be treated as manual. Photos are content: a change bumps menu_version. photos: [] = no photos, also when the channel hides photos.

Orders

{
  "fulfillment": "pickup",
  "customer": {
    "name": "Jana Nováková",
    "phone": "+421 900 123 456",
    "email": "jana@example.com"
  },
  "items": [
    {
      "item_id": "3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01",
      "quantity": 2
    }
  ],
  "payment_method": "in_person",
  "client_total_cents": 1980
}

curl https://vittles.eu/api/v1/orders \
  -X POST \
  -H "Authorization: Bearer $VITTLES_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fulfillment":"pickup","customer":{"name":"Jana Nováková","phone":"+421 900 123 456","email":"jana@example.com"},"items":[{"item_id":"3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01","quantity":2}],"payment_method":"in_person","client_total_cents":1980}'

// Server-side only (route handler, API route, cron). Never in the browser.
const res = await fetch("https://vittles.eu/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VITTLES_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey, // crypto.randomUUID(), kept for every retry
  },
  body: JSON.stringify({
    "fulfillment": "pickup",
    "customer": {
      "name": "Jana Nováková",
      "phone": "+421 900 123 456",
      "email": "jana@example.com"
    },
    "items": [
      {
        "item_id": "3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01",
        "quantity": 2
      }
    ],
    "payment_method": "in_person",
    "client_total_cents": 1980
  }),
});
const body = await res.json();
if (!res.ok) {
  // body.error.code is stable; body.error.message is for your log
  throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
}

// wp-config.php: define('VITTLES_API_KEY', 'sk_live_…'); — never in a theme option or in JavaScript.
$response = wp_remote_request('https://vittles.eu/api/v1/orders', [
    'method'  => 'POST',
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . VITTLES_API_KEY,
        'Content-Type'  => 'application/json',
        'Idempotency-Key' => wp_generate_uuid4(), // keep the same value for every retry
    ],
    'body'    => wp_json_encode([
            'fulfillment' => 'pickup',
            'customer' => [
                'name' => 'Jana Nováková',
                'phone' => '+421 900 123 456',
                'email' => 'jana@example.com',
            ],
            'items' => [
                [
                    'item_id' => '3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01',
                    'quantity' => 2,
                ],
            ],
            'payment_method' => 'in_person',
            'client_total_cents' => 1980,
        ]),
]);
if (is_wp_error($response)) { error_log('Vittles: ' . $response->get_error_message()); return; }
$body = json_decode(wp_remote_retrieve_body($response), true);
if (wp_remote_retrieve_response_code($response) >= 400) {
    error_log('Vittles ' . $body['error']['code'] . ': ' . $body['error']['message']);
}

Order status

There are no webhooks. Poll GET /orders/{id} every 10 seconds through your own server (the key must not reach the browser) and stop when is_final is true. Send If-None-Match to get 304 while nothing changed.

curl https://vittles.eu/api/v1/orders/8f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f \
  -H "Authorization: Bearer $VITTLES_API_KEY" \
  -H "Accept-Language: en"

// Server-side only (route handler, API route, cron). Never in the browser.
const res = await fetch("https://vittles.eu/api/v1/orders/8f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VITTLES_API_KEY}`,
  },
});
const body = await res.json();
if (!res.ok) {
  // body.error.code is stable; body.error.message is for your log
  throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
}

// wp-config.php: define('VITTLES_API_KEY', 'sk_live_…'); — never in a theme option or in JavaScript.
$response = wp_remote_request('https://vittles.eu/api/v1/orders/8f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f', [
    'method'  => 'GET',
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . VITTLES_API_KEY,
    ],
]);
if (is_wp_error($response)) { error_log('Vittles: ' . $response->get_error_message()); return; }
$body = json_decode(wp_remote_retrieve_body($response), true);
if (wp_remote_retrieve_response_code($response) >= 400) {
    error_log('Vittles ' . $body['error']['code'] . ': ' . $body['error']['message']);
}

Quote

Discounts are computed from discount.base_cents — the lines that are not add-ons (food and drinks) and not from the daily menu. Packaging and the delivery fee are never discounted: a 10 % coupon on a 17.00 order with a 0.50 box and a 4.50 delivery fee takes 1.70 off, and subtotal_cents (22.00) still counts every line. Coupons and address discounts don't apply to daily-menu lines either (daily.discounts_apply: false, items[].daily: true in the quote) — they still count towards a delivery zone's minimum and free_from_cents. A coupon's minimum order value and the discount cap use the same base. Send the guest's coupon in coupon whenever they enter one; ordering.form.coupon in GET /menu is only a hint whether to show the field.

{
  "fulfillment": "pickup",
  "customer": {
    "name": "Jana Nováková",
    "phone": "+421 900 123 456",
    "email": "jana@example.com"
  },
  "items": [
    {
      "item_id": "3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01",
      "quantity": 2
    }
  ],
  "payment_method": "in_person",
  "client_total_cents": 1980
}

curl https://vittles.eu/api/v1/orders/quote \
  -X POST \
  -H "Authorization: Bearer $VITTLES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fulfillment":"pickup","customer":{"name":"Jana Nováková","phone":"+421 900 123 456","email":"jana@example.com"},"items":[{"item_id":"3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01","quantity":2}],"payment_method":"in_person","client_total_cents":1980}'

// Server-side only (route handler, API route, cron). Never in the browser.
const res = await fetch("https://vittles.eu/api/v1/orders/quote", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VITTLES_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "fulfillment": "pickup",
    "customer": {
      "name": "Jana Nováková",
      "phone": "+421 900 123 456",
      "email": "jana@example.com"
    },
    "items": [
      {
        "item_id": "3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01",
        "quantity": 2
      }
    ],
    "payment_method": "in_person",
    "client_total_cents": 1980
  }),
});
const body = await res.json();
if (!res.ok) {
  // body.error.code is stable; body.error.message is for your log
  throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
}

// wp-config.php: define('VITTLES_API_KEY', 'sk_live_…'); — never in a theme option or in JavaScript.
$response = wp_remote_request('https://vittles.eu/api/v1/orders/quote', [
    'method'  => 'POST',
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . VITTLES_API_KEY,
        'Content-Type'  => 'application/json',
    ],
    'body'    => wp_json_encode([
            'fulfillment' => 'pickup',
            'customer' => [
                'name' => 'Jana Nováková',
                'phone' => '+421 900 123 456',
                'email' => 'jana@example.com',
            ],
            'items' => [
                [
                    'item_id' => '3f8b2c1e-6a4d-4c0a-9d2e-1b5f7a8c9d01',
                    'quantity' => 2,
                ],
            ],
            'payment_method' => 'in_person',
            'client_total_cents' => 1980,
        ]),
]);
if (is_wp_error($response)) { error_log('Vittles: ' . $response->get_error_message()); return; }
$body = json_decode(wp_remote_retrieve_body($response), true);
if (wp_remote_retrieve_response_code($response) >= 400) {
    error_log('Vittles ' . $body['error']['code'] . ': ' . $body['error']['message']);
}

Delivery zones and addresses

Delivery comes in two modes, announced in GET /menu as ordering.delivery.mode. In anywhere mode any address text is accepted and the fee is the venue's on_delivery add-on. In zones mode the venue has drawn delivery zones: call POST /addresses/suggest as the guest types (from 3 characters, debounced ~300 ms, always from your server), show the suggestions with their delivery block — zone, estimated road distance, fee, minimum order and lead time, or null outside every zone — and send the chosen suggestion's address_token in POST /orders/quote and POST /orders. The token is signed, valid 30 minutes and only for this venue; never store it or put it in a URL, it carries coordinates. Without a token the server geocodes address once and takes the first suggestion with precision of street or better. A place-only address is refused (422 address_imprecise), an address outside every zone too (422 delivery_out_of_zone), and a food base under the zone's minimum answers 422 delivery_minimum_not_met with details.minimum_cents and details.missing_cents. The fee appears as an add-on line with zone_id and up_to_m; free_from_cents in delivery says from which food base it drops to 0. Zone geometry is never exposed. Zones may overlap: among zones defined by named places (a town, a village, a part of a town) the smallest place that contains the address wins, so a part of a town with its own price beats the whole town; otherwise the zone order the owner set decides. When the lookup is unavailable (503 address_lookup_unavailable) offer pickup — a delivery order in zone mode cannot be placed without a resolved address.

{
  "query": "Hlinská 12, Žilina"
}

curl https://vittles.eu/api/v1/addresses/suggest \
  -X POST \
  -H "Authorization: Bearer $VITTLES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Hlinská 12, Žilina"}'

// Server-side only (route handler, API route, cron). Never in the browser.
const res = await fetch("https://vittles.eu/api/v1/addresses/suggest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VITTLES_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "Hlinská 12, Žilina"
  }),
});
const body = await res.json();
if (!res.ok) {
  // body.error.code is stable; body.error.message is for your log
  throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
}

// wp-config.php: define('VITTLES_API_KEY', 'sk_live_…'); — never in a theme option or in JavaScript.
$response = wp_remote_request('https://vittles.eu/api/v1/addresses/suggest', [
    'method'  => 'POST',
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . VITTLES_API_KEY,
        'Content-Type'  => 'application/json',
    ],
    'body'    => wp_json_encode([
            'query' => 'Hlinská 12, Žilina',
        ]),
]);
if (is_wp_error($response)) { error_log('Vittles: ' . $response->get_error_message()); return; }
$body = json_decode(wp_remote_retrieve_body($response), true);
if (wp_remote_retrieve_response_code($response) >= 400) {
    error_log('Vittles ' . $body['error']['code'] . ': ' . $body['error']['message']);
}

Inquiries

{
  "text": "2x Margherita\n1x Coca-Cola",
  "customer": {
    "name": "Jana Nováková",
    "phone": "+421 900 123 456"
  }
}

curl https://vittles.eu/api/v1/inquiries \
  -X POST \
  -H "Authorization: Bearer $VITTLES_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text":"2x Margherita\n1x Coca-Cola","customer":{"name":"Jana Nováková","phone":"+421 900 123 456"}}'

// Server-side only (route handler, API route, cron). Never in the browser.
const res = await fetch("https://vittles.eu/api/v1/inquiries", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VITTLES_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey, // crypto.randomUUID(), kept for every retry
  },
  body: JSON.stringify({
    "text": "2x Margherita\n1x Coca-Cola",
    "customer": {
      "name": "Jana Nováková",
      "phone": "+421 900 123 456"
    }
  }),
});
const body = await res.json();
if (!res.ok) {
  // body.error.code is stable; body.error.message is for your log
  throw new Error(`${body.error.code}: ${body.error.message} (${body.error.request_id})`);
}

// wp-config.php: define('VITTLES_API_KEY', 'sk_live_…'); — never in a theme option or in JavaScript.
$response = wp_remote_request('https://vittles.eu/api/v1/inquiries', [
    'method'  => 'POST',
    'timeout' => 10,
    'headers' => [
        'Authorization' => 'Bearer ' . VITTLES_API_KEY,
        'Content-Type'  => 'application/json',
        'Idempotency-Key' => wp_generate_uuid4(), // keep the same value for every retry
    ],
    'body'    => wp_json_encode([
            'text' => '2x Margherita
1x Coca-Cola',
            'customer' => [
                'name' => 'Jana Nováková',
                'phone' => '+421 900 123 456',
            ],
        ]),
]);
if (is_wp_error($response)) { error_log('Vittles: ' . $response->get_error_message()); return; }
$body = json_decode(wp_remote_retrieve_body($response), true);
if (wp_remote_retrieve_response_code($response) >= 400) {
    error_log('Vittles ' . $body['error']['code'] . ': ' . $body['error']['message']);
}

Errors

Every non-2xx response is { "error": { "code", "message", "param"?, "details"?, "request_id" } }. Branch on code — it never changes. message is for your log, in the Accept-Language language (sk | en). X-Request-Id is on every response; quote it when writing to support.

Idempotency

Send Idempotency-Key on POST /orders and POST /inquiries. The same key always returns the same order (HTTP 200, replayed: true), even when the body differs. Generate it when the guest first submits and keep it across every retry — a lost response, not a double click, is what creates duplicate orders.

Idempotency-Key: 6d1f0c1e-3b8a-4f0e-9c1d-2a7b8e9f0a1b

Rate limits

Per key, four separate buckets: 30 writes per minute (POST /orders, POST /inquiries, POST /addresses/suggest), 60 quotes per minute (POST /orders/quote — quoting never spends the write bucket), 600 status reads per minute (GET /orders/{id}) and 120 menu reads per minute (GET /menu — a 304 counts too; cache the menu on your side and revalidate with If-None-Match instead of fetching it on every page view). Over the limit you get 429 rate_limited with Retry-After in seconds. If the limiter itself is unreachable the API fails closed with 503.

Versioning

The version is the first path segment after /api (currently v1). Fields are only added, never renamed or removed, within v1; new enum values may appear — treat unknown values as unknown, not as errors. A breaking change gets a new segment (v2) and v1 keeps working for at least six months after the announcement.

AI prompt

Working with an AI assistant on the venue's website? Paste this brief. It says which endpoint to use, where the key must live, how to retry, and what to show the guest — the mistakes it warns about are ones that actually happened.

Connect this website to Vittles — the venue's ordering system. Follow this
brief exactly; do not work around anything marked RULE, even when a shortcut
looks simpler.

## What I have

- Website: {{Astro / Next.js / WordPress / static HTML — and the repository URL or path}}
- Order form: {{a cart with "add" buttons / a plain text box "what would you like" / nothing yet}}
- Vittles URL: {{https://vittles.eu}}
- API key: it lives in the server's secrets. I will never paste it into this chat.
- Documentation: {{https://vittles.eu}}/docs/api and {{https://vittles.eu}}/api/v1/openapi.json

## Decide the path first

Vittles has two entrances. Pick ONE per form — never both.

A) The site knows the menu and the guest picks items into a cart
   → POST /api/v1/orders. An ORDER is created; the counter rings.

B) The site has a plain text box ("what would you like?")
   → POST /api/v1/inquiries. An INQUIRY is created: text and nothing else.
   The counter does NOT ring until a person confirms it.

If the form e-mails the kitchen today, it is path B: repoint the form to your
server, add the header, done. Do path A only when the guest really picks
items from a list you fetched from Vittles.

Tell me which path you chose and why before writing code.

If the site only needs to SHOW the menu and take orders without custom code,
do neither: paste the widget snippet from the venue's Channels page
(`<div data-vittles-venue="…">` + `embed.js`) and stop here — see
{{https://vittles.eu}}/docs/embed. Keys and the widget belong to the venue's
Ultra plan; on a lower plan the API answers 403 `plan_required`.

## RULE 1 — the key never leaves the server

Authentication is `Authorization: Bearer <key>`. Whoever has the key can
create orders in the venue's name.

- read the key from an environment variable WITHOUT a public prefix
  (`VITTLES_API_KEY`, not `PUBLIC_VITTLES_API_KEY`, not `NEXT_PUBLIC_*`)
- call Vittles ONLY from the server (Astro endpoint with
  `export const prerender = false`, Next route handler, WordPress
  `wp_remote_request`); the browser calls YOUR endpoint, which calls Vittles
- never send the `Origin` header: Vittles answers 403 `secret_key_in_browser`
  to a secret key that arrives from a browser
- at the end, show me that the key is not in the client bundle

## RULE 2 — Vittles computes the prices

The server prices every line from its own menu. Whatever you send as a price
is only a checksum.

- take item ids and prices from GET /api/v1/menu; never hard-code them
- prices are integer CENTS: 9.50 EUR is `950`, not `9.5`
- add-ons (boxes, cutlery, delivery fee) come from `addons` rules and the
  server adds them itself — do not send them as items
- send `client_total_cents` (the subtotal you showed, add-ons included) only
  as a check; when the response says `total_mismatch: true`, show the guest
  `total_cents` from the response — that is what they pay
- to show the exact total before sending, call POST /api/v1/orders/quote with
  the same body; nothing is created

## RULE 3 — idempotency

- when the guest first submits the cart, generate `crypto.randomUUID()` and
  keep it in the session
- send it as the `Idempotency-Key` header on EVERY retry of that cart (after
  an error, a timeout, a 429, a 5xx)
- do NOT change the key after a failure. That is the whole point: the danger
  is not a double click but a lost response — the guest adds a dessert,
  submits again, and without the same key two orders exist
- a response with `replayed: true` (HTTP 200) means the order already
  existed. It is not an error; show the confirmation

## RULE 4 — what to show the guest

Path A (order):
- after 201 show `number` and `total_cents` from the response; for
  `bank_transfer` / `qr_payment` show `payment.transfer` (IBAN, recipient,
  variable symbol) — it comes only in this response
- keep `id` in YOUR guest session (cookie / sessionStorage). Never in a URL,
  an e-mail, a log or analytics — it is the only ticket to the status
- poll the status through your own server: GET /api/v1/orders/{id} every
  10 seconds, send `If-None-Match` with the last `ETag`, and stop when
  `is_final` is true. `expired` means the day closed without anyone
  finishing the order — do not show it as "done"
- a daily-menu line has `daily: true` in the status: print it as
  `label · name` ("Menu 1 · …") with `soup` under it, the same way the
  kitchen ticket does
- required guest fields depend on `fulfillment`: read
  `ordering.form.required` from the menu instead of guessing. The phone
  (`customer.phone`) is required on EVERY order, table orders too — make
  the phone field mandatory and send the number in full (`+421 …` or
  `09…`); a missing or incomplete one is 400 `invalid_request` with
  `param: "customer.phone"`
- delivery: read `ordering.delivery.mode` from the menu. In `zones` mode
  call POST /api/v1/addresses/suggest through your server as the guest
  types the address (from 3 characters, debounced ~300 ms), show each
  suggestion with its `delivery` block (zone, distance, fee, minimum, lead
  time — or "we do not deliver here" when it is `null`), let the guest pick
  one that is not `precision: "place"`, and send its `address_token` in
  the quote and the order. Never store the token or put it in a URL. On
  422 `delivery_out_of_zone` / `address_imprecise` / `address_unresolved`
  offer pickup; on `delivery_minimum_not_met` show `details.missing_cents`
- address suggestions come from Geoapify, whose Free plan terms require
  attribution: show "Powered by Geoapify" as a link to
  https://www.geoapify.com/ right under the suggestion list whenever it is
  visible. Do not translate it and do not hide it

Path B (inquiry):
- after 201 say "We got it, we will get back to you" — NOT "Order accepted".
  No order exists yet and the venue may decline
- the status cannot be read: an inquiry `id` is not an order id
- send the guest's `text` UNCHANGED. Do not join lines, do not strip `\n`,
  do not trim the inside. Vittles splits the text by line breaks and `;` —
  a comma is NOT a separator — and your "normalisation" breaks the matching

## RULE 5 — menu and cache

- GET /api/v1/menu returns an `ETag`. Send `If-None-Match` and reuse what
  you have on 304
- the tag covers the whole body including `ordering.state`; do not build your
  own cache on `menu_version`
- GET /api/v1/menu is rate-limited per key (120 per minute, a 304 counts
  too): keep the menu in your server's cache and revalidate it at most once
  a minute — never call Vittles once per page view of your site
- when `ordering.state` is not `open`, hide the order button and show
  `ordering.message` (it is in the language of your `Accept-Language`);
  `resumes_at` says when a pause ends
- show an item with `available: false` but do not let the guest order it.
  Hiding it means the guest looks for it; leaving it orderable means 422
  after the whole cart was filled
- show every item, but offer ordering only for `orderable: true` —
  `orderable: false` with `available: true` means "in the restaurant only"
- `daily` is today's daily menu, or `null`. It is NOT a category: show it
  as its own section above the menu while `daily.state` is `upcoming`
  (no add button yet — ordering starts at `orders_from`) or `open`, and
  hide it when it is `ended`. The state flips at `orders_from` and
  `orders_until` without any edit and the `ETag` flips with it — refetch
  the menu then, never decide the window from the guest's clock. Offer the
  add button only for `orderable: true`. A dish with `includes_soup: true`
  needs `soup_id` (a `daily.soups[].id` with `available: true`) on
  its line when `soup_choice_required` is true. Coupons and address discounts never
  apply to it (`discounts_apply: false`) — do not show them as discounted
- an item with a non-empty `variants` (sizes such as Kofola 0.3 l / 0.5 l)
  is ONE item: show its `price_cents` as "from …", let the guest pick one
  of `variants[]` (show its `label`, grey out `available: false`) and
  send the pick as `variant_id` next to `item_id`. Two sizes are two cart
  lines. Without `variant_id` the order is 422 `variant_required`
- offer only `ordering.fulfillment_types` and `ordering.payment_methods`

## RULE 6 — errors

Every non-2xx response is `{ "error": { "code", "message", "param"?,
"details"?, "request_id" } }`. Branch on `code`; log `message` and
`request_id`.

- 400 `invalid_request` → `param` names the field; that is YOUR bug, fix the
  body. The API is strict: unknown fields are rejected, free data goes in
  `metadata`
- 401 / 403 → your configuration (key, scope, Origin). Log it, tell the guest
  "ordering is temporarily unavailable"; 403 `plan_required` means the
  venue's plan does not include the API (`details.plan`) — tell the venue,
  not the guest
- 409 `ordering_disabled` / `ordering_paused` (`details.resumes_at`) /
  `ordering_closed` → show `message` and do NOT retry; bring the button back
  after `resumes_at` or when the menu says `ordering.state: "open"`
- 422 `item_unavailable` / `item_not_orderable` / `item_unknown` → refresh
  the menu and let the guest fix the cart; `coupon_*` → show `message` at
  the coupon field; `fulfillment_not_offered` / `payment_method_not_offered`
  → refresh the menu
- 422 `daily_menu_closed` → the daily menu's window is over (or it was
  withdrawn): refresh the menu and remove the daily lines from the cart;
  `daily_soup_required` → ask the guest for the soup (`details.reason`
  is `choose` or `invalid`); `daily_soup_not_sold_alone` → that soup
  comes only with a daily dish
- 422 `variant_required` / `variant_invalid` → the line of
  `details.item_name` needs a size: refresh the menu and let the guest pick
  one of that item's `variants` again
- 429 `rate_limited` → respect `Retry-After`, pass it through your endpoint
  to the client, retry with the SAME Idempotency-Key
- 5xx → retry with exponential backoff and the same Idempotency-Key

## Test first

Ask the venue for an `sk_test_` key. It runs the same validation and pricing,
stores nothing and the counter stays silent; the response has
`id: "test_…"`, `number: 0`, `test: true`, and GET /api/v1/orders/test_…
walks through the statuses by age so you can test polling end to end. Switch
to the `sk_live_` key only when the whole flow works.

## Do not

- do not send a venue id anywhere. The venue comes from the key
- do not call anything outside /api/v1 with the key
- do not send `coupon: ""` when the field is empty — omit the field
- do not rely on the Vittles rate limit as your form protection: it sees the
  key, not the guest's IP, and it is shared by the whole site. Add your own
  throttle and a honeypot

## Steps

1. Tell me which path you chose.
2. Write the server endpoint that is the only place that knows the key.
3. Wire the existing form to it. If it e-mails today, keep the e-mail
   running too — until the venue trusts the counter, the second path is the
   safety net.
4. Show me exactly what body is sent and where the key is read.
5. Run it against the test key and show me the response.