# Winteride Partner API > Book airport-to-ski-resort transfers (the French and Swiss Alps) from a travel agency's or a hotel's own system or AI agent. > Base URL `https://winteride.com/api/partner/v1` (or `https://partners.winteride.com/api/partner/v1`, the same API). Authenticate > every request with your organisation's API key: > `Authorization: Bearer wrp_...`. Money is integer minor units (cents). Contract version 1.22.0. This file is GENERATED from the published contract (`openapi.yaml`) and the partner guide (`PARTNER_GUIDE.md`) by `apps/api/tools/partner_docs.py`, and a test holds it equal to them: it cannot say something the API does not do. It is published at https://docs.winteride.com/partner-api/llms.txt, beside the guide and the contract. Feed it to an AI agent whole. An agent that speaks MCP can instead connect to the partner connector, `POST /api/partner/v1/mcp` with the same key (section "AI agents" below), whose tools run these very doors. ## How to use this API correctly (the rules an agent must keep) 1. Authenticate with the partner's API key on EVERY request: `Authorization: Bearer wrp_...`. Never put the key in a URL, a log or a browser. A wrong, revoked or missing key is `401 authentication_required`. 2. You only ever see and act on your own organisation's bookings. Another partner's reference is `404 not_found`. 3. Money is integer minor units: `16200` is EUR 162.00. Every price you are given is your NET (after your commission). 4. Quote before you book, with the same journey. A shared seat needs `flight_no` or `flight_time`; without one `shared.available` is false with `reason: no_flight_time`. 5. A flat booking states `price_total_cents` = the `price_cents` the quote showed for that service. It is only COMPARED: a difference is `409 price_changed` and nothing is written. Quote again and book at the new price. It is never charged. 6. Send your own idempotency key with every booking (`client_ref` in the body, or the `Idempotency-Key` header) and the SAME key on every retry: a repeat answers `200` with `duplicate: true` and the booking you already have; nothing is booked twice. 7. Amend in two steps: preview, then commit with `expected_delta_minor` = the preview's `price.delta_minor`. 8. Read `cancel_preview` on the booking before cancelling; cancelling cannot be undone. 9. Booking, amending and cancelling change money: an AI agent confirms with its human first. 10. Branch on the error `error` code, never on the message. A field the API does not read is refused `422` by name. 11. Respect the limits: on `429 rate_limited` wait the `Retry-After` seconds. ## Authentication (from the guide) Your server authenticates with your organisation's **API key**, sent on **every** request: ``` Authorization: Bearer wrp_… ``` - **Your key is your agency's (or hotel's).** It acts only as your account, on these doors and nothing else: not your partner portal, not another partner's bookings. Keep it on your server only — never in a browser, a mobile app, a URL or a log. - **Getting one.** Winteride hands you your first key when your account goes live. After that you manage your keys yourself in your partner portal's **organisation settings → API keys**: create one (give it a name, such as "production server"), rename it, **rotate** it (the old key stops at once and a new one is shown) or **revoke** it. Up to five keys can be live at once, so you can move a server to a new key before revoking the old one. Winteride can do the same for you on request. - **A key is shown once**, when it is made or rotated, and never again: we keep only a fingerprint of it and its first characters (`wrp_` and eight more), which the portal shows beside its name and when it was last used. Lost a key? Rotate it. - **It does not expire.** A wrong, revoked or rotated key is `401 authentication_required` from the next request. Calls are limited per key (§12). **Trying the API by hand.** A signed-in partner **session** works on the same doors: your agency is given a **login address**, an e-mail that receives your sign-in codes (there is no password since 2026-11-05), and a signed-in session gives you a **bearer token** that expires after hours: 1. Ask for a code. It is e-mailed to the login address; the answer is the same whatever the address, `{"sent": true, "phone_path": true}` (an account with no email signs in with its phone instead: `POST /api/auth/code/phone` with `{"phone": "+…", "portal": "partner"}`, then the verification with `"phone"` in place of `"email"`). At most three codes go to one address every ten minutes: ```json { "email": "reservations@your-agency.example", "portal": "partner" } ``` 2. Sign in with the six-digit code (`POST /api/auth/code/verify`, the same body with `"code"`). The answer carries the token and when it expires: ```json { "token": "…", "expires_at": "2026-10-20T09:00:00+00:00", "user": { "id": "…", "kind": "partner", "is_staff": false, "is_driver": false, "is_supplier": false, "is_customer": false, "is_partner": true, "display_name": "Your Agency", "must_change_password": false } } ``` 3. Send the token as above. When it expires (`expires_at`), sign in again. Keep it **server-side only** — never in browser or mobile code. A code lives 5 minutes and three wrong tries spend it; an address is sent at most three codes every 10 minutes and eight a day. `POST /api/auth/code/request` (`/verify`) allow ten tries every 10 minutes from one address. A missing, expired or wrong key or token is `401 authentication_required`. A staff, driver or customer session is refused here: these doors serve partners only (agents and hotels; some doors are for agents alone, as noted). > **Planned / not yet available:** a sandbox. Every key works on the live platform. ## Conventions (from the guide) - **Money is integer minor units** (cents of a euro): `8900` = €89.00. Prices are whole euros: a fare is rounded **up** to the whole euro, and so is your net after commission. The flat quote and booking doors (§4) name amounts `price_cents` / `price_total_cents`; every other answer names them `…_minor` (`net_minor`, `gross_minor`). It is the same unit. - **Your price is your net.** Every figure you are given is already net of your commission (shared seats and private transfers may carry different commissions). Where Winteride has agreed a fixed shared price with you for a route and party size, that agreed price is what `shared.price_cents` says, and it does not move when the list price does. - **Booking references** look like `WR-2026-00001`. Price offers are `WO-2026-00001` until accepted. Everywhere a booking is named in a path you may use its **reference or its id** (§4, Step 4). - **Dates** are `YYYY-MM-DD` and mean the **airport's local day**; times are ISO-8601 instants (`2026-12-17T07:50:00Z`); the API answers instants in UTC (`…+00:00`). - **Errors** always use one envelope: `{ "error": "", "message": "…", "language": "en", "context": { … } }` (`context` appears when there is something to name — the field, the allowed values). Branch on `error`, never on the message. `message` is for a person to read and is in English unless you ask for another language: send `Accept-Language: he` or `fr` and it comes in Hebrew or French; `language` (and the `Content-Language` header) says which it is in. `error` and `context` never change with the language. When a Hebrew or French `message` is the code's general sentence, the precise English one may ride along as `detail`: ```json { "error": "not_found", "message": "No such booking.", "language": "en", "context": { "booking_id": "WR-2099-99999" } } ``` - **Nothing is ignored.** A field the API does not read is refused `422 validation_error`, naming it; a price, a source, a partner or a channel in a body is refused by name. (This is how the API protects you from a typo that would otherwise be silently dropped.) The same holds for an extra: a quote names every `supplements` id it could not price in `supplements_ignored`, and a booking that asks for one is refused `422 validation_error` (`context.reason: supplement_not_priced`, `context.ignored`), nothing written. ## The booking flow (from the guide) ``` reference ─▶ quote ─▶ book ─▶ read ─▶ voucher ─▶ (amend / cancel) ``` ### Step 0 — Your profile and language ```bash curl https://$HOST/api/partner/v1/me -H "Authorization: Bearer $WINTERIDE_API_KEY" curl -X PATCH https://$HOST/api/partner/v1/me \ -H "Authorization: Bearer $WINTERIDE_API_KEY" -H "Content-Type: application/json" \ -d '{ "language": "fr" }' ``` ```json { "user_id": "…", "kind": "agent", "legal_name": "Your Agency", "contact_name": "Ana Novak", "display_name": "Your Agency", "email": "reservations@your-agency.example", "language": null, "settle_default": "credit", "terms": { "commission_bps": 1000, "commission_bps_shared": null, "credit_limit_minor": 5000000, "settlement_currency": "EUR" }, "credit": { "balance_minor": 0, "limit_minor": 5000000, "available_minor": 5000000, "currency": "EUR" } } ``` Every voucher and price offer we send you goes out in **one language of your choosing** — `en`, `he` or `fr`. `PATCH /me` sets it and **nothing else**; `{"language": null}` returns to the default, which decides from your phone number (+972 → Hebrew, otherwise English). Any other key (the body is `language`, not `lang`) is refused `422` naming it. ```json { "language": "fr" } ``` ### Step 1 — Load reference data (cache it) ```bash curl https://$HOST/api/partner/v1/reference -H "Authorization: Bearer $WINTERIDE_API_KEY" ``` ```json { "airports": [ { "id": "…", "code": "GVA", "name": "Geneva", "country": "CH", "allows_shared": true } ], "resorts": [ { "id": "…", "slug": "val-thorens", "name": "Val Thorens", "country": "FR", "allows_shared": true } ], "vehicle_classes": [ { "id": "…", "name": "Van (up to 8)", "max_pax": 8, "max_luggage": 8 } ] } ``` The response has exactly three arrays. The flat doors below take `airports[].code` and `resorts[].slug`; the quote-first doors (Step 2b) take the `id`s. A reference row never carries a price, a price group or a luggage factor. > **Planned / not yet available:** a `route_map` (`airport code → [resort slug]`) saying which > resorts each airport serves. Ask a quote instead. ### Step 2 — Get a quote One call prices **both** services for a journey: the shared seat and every private vehicle that fits. Name the journey by its codes: ```bash curl -X POST https://$HOST/api/partner/v1/quotes \ -H "Authorization: Bearer $WINTERIDE_API_KEY" -H "Content-Type: application/json" -d @quote.json ``` ```json { "airport_code": "GVA", "resort_slug": "val-thorens", "pax": 2, "date": "2026-12-17", "luggage": 2, "trolley": 2, "ski": 2, "flight_no": "LY345", "direction": "arrival" } ``` The answer is `200`. **This is the exact shape**; every price is already your **net**: ```json { "in_season": true, "season_tier": "high", "season_period": "2026-27", "flight": { "flight_no": "LY345", "found": true, "time": "2026-12-17T07:50:00+00:00" }, "travel": null, "private": [ { "class": "Van (up to 8)", "vehicle_class_id": "…", "max_pax": 8, "max_luggage": 8, "on_request": false, "price_cents": 27000, "currency": "EUR" } ], "shared": { "available": true, "price_cents": 16200, "currency": "EUR", "seats_remaining": 6, "on_request": false, "notices": [ { "code": "shared_seat", "title": "Shared transfer", "text": "A shared transfer costs less and is less flexible. The pickup time can change until the day before the trip, when we confirm it. Please check your email until then: we send any new time there." } ] }, "supplements": [ { "id": "…", "name": "Child seat", "price_cents": 1500 } ] } ``` | Field | Meaning | |---|---| | `in_season`, `season_tier`, `season_period` | The pricing period the date falls in. `in_season` is `true` on every quote that is returned: a date no pricing period covers is refused `404 not_found` for both services instead. | | `flight` | `{flight_no, found, time}` when you sent a flight number (`found: true` when its time came from our timetable or the live feed, `false` when we could not place it); `{found: false}` when you sent none. | | `travel` | Always `null` today: the Partner API carries no road estimate. | | `private[]` | One entry per vehicle class that **fits** the party and its luggage and **can be booked on your account**, cheapest first. Luggage and ski are included in a private price; `trolley` is carried for the driver and never priced. `on_request: true` — this class is not confirmed automatically (a minibus or coach always is, and so is a class when too few of our vans are free): the booking is held `on_request` until Winteride arranges the vehicle. `vehicles` appears only on a multi-vehicle option. | | `shared` | A seat on a van several parties share: `{available: true, price_cents, currency, seats_remaining, on_request, notices}`, or `{available: false, reason, hint}`. Since 1.20.0 an available seat carries `notices`: one `Notice`, `{code: "shared_seat", title, text}`, in your language (`Accept-Language`; English when you send none) - what a shared seat is: it costs less and is less flexible, and its pickup time can change until the day before the trip. **Show it to your client wherever you show the seat**, and tell your client to read their email until then. `seats_remaining` is the free seats on the matching van right now (`null` while no van is scheduled for that time). `on_request: true` means the route's minimum party is not met yet: you can still book, and it confirms once enough passengers join. | | `supplements[]` | The extras you may ask for in `supplements: [{id, qty}]` (live, in the quote's currency, at the listed price). Asked, they are added to both services' prices. | | `supplements_ignored[]` | Only on a quote that sent `supplements`: each asked id the engine could **not** price, as `{id, reason}` (`unknown`, `inactive`, `not_extra`, `other_currency`); `[]` when every one was priced. An unpriced extra adds nothing to the price, and is never dropped without being named. | There is **no top-level `currency`** — each option carries its own. > ### ⚠️ Read `shared.available`, not `shared.eligible` > > Earlier versions of this guide printed an internal quote shape — `shared.eligible`, `amount_cents`, > `flight.no`. None of those fields exist in what the API sends, so an integration written against > them reads `undefined`, treats it as false, and concludes that Winteride has no shared service at > all. It is the same quote either way; only the names differ. The map: > > | You may have coded | The field that exists | > |---|---| > | `shared.eligible` | **`shared.available`** | > | `shared.amount_cents` | **`shared.price_cents`** | > | `private[].amount_cents` | **`private[].price_cents`** | > | `private[].class_id` | **`private[].vehicle_class_id`** | > | `flight.no` | **`flight.flight_no`** | > | `shared.availability` (traffic light) | **`shared.seats_remaining`** (a number) | > | `shared.min_met: false` | **`shared.on_request: true`** | #### Why `shared` is not offered, and what to change > **If you want a shared price, send `flight_no` or `flight_time`.** A shared seat is pooled on a > **landing time** (or, on a departure, the flight's departure time). A quote that carries neither > gives the engine nothing to pool on, and `shared` comes back `available: false` with > `reason: "no_flight_time"` — no matter how eligible the route is. **Private prices are returned > either way** (priced as of midday of the day when you give no time), so a quote without a time looks > like "this route has no shared service", which is the single most common support question we get. > A `pickup_time` alone is not a flight. ```json { "airport_code": "GVA", "resort_slug": "val-thorens", "pax": 2, "date": "2026-12-17", "direction": "arrival" } ``` ```json { "in_season": true, "season_tier": "high", "season_period": "2026-27", "flight": { "found": false }, "travel": null, "private": [ { "class": "Van (up to 8)", "vehicle_class_id": "…", "max_pax": 8, "max_luggage": 8, "on_request": false, "price_cents": 27000, "currency": "EUR" } ], "shared": { "available": false, "reason": "no_flight_time", "hint": "Shared seats are pooled on the landing time. Send `flight_no`, or `flight_time` (ISO 8601) when there is no flight number yet, and the shared price will be quoted." }, "supplements": [] } ``` When your client has not booked a flight yet, send the expected landing time instead — a time is enough to be offered a seat, because a seat is pooled on the **time**, not on the number: ```json { "airport_code": "GVA", "resort_slug": "val-thorens", "pax": 2, "date": "2026-12-17", "flight_time": "2026-12-17T07:50:00Z", "direction": "arrival" } ``` Every unavailable `shared` carries a `hint` (a sentence you can show) and one of these reasons: | `reason` | Meaning | |---|---| | `no_flight_time` | No `flight_no` and no `flight_time` was sent. Send one and ask again. | | `flight_time_unknown` | You sent a `flight_no` and we have no time for it on that day. Send its `flight_time`. | | `below_min` | The route needs a minimum party for a shared van (it can still be requested). | | `shared_group_too_large` | The party fills a vehicle of its own: priced as private. | | `shared_luggage_limit` | Shared carries about one suitcase and one ski bag per person. | | `airport_not_shared` / `resort_not_shared` | Winteride runs no shared service from this airport / to this resort. | | `shared_closed_off_season` | The shared service is not running on that date. | | `not_tlv_or_near_tlv` | No shared van runs close enough to that arrival time on that date. | | `general_shared_no_price` | No shared price is published for this route (or this party size) yet. | | `flight_not_listed` / `flight_wrong_airport` / `flight_not_operating_on_date` | The flight number is not on our list, serves another airport, or does not fly that day. | | `shared_pickup_off_its_flight` | The pickup you gave does not fit the flight's time. | | `route_currency_not_settlement_currency` | The route is priced in another currency than your credit line is kept in. | | `not_available` | Any other reason; `hint` is `null`. | A quote refused for both services is the engine's own refusal (`404 not_found` when no price covers the route, date or party; `422` when the request is wrong), never an empty quote. **Round trips.** Add `"trip_type": "round_trip"` (or `"round_trip": true`) and the return: `return_flight_no` with `return_date`, or `return_flight_time`, or `return_pickup_time`; the return's own bags are `return_luggage` and `return_ski`. A round trip is one price for both legs, with the round-trip discount. Return fields on a one-way quote are refused; a return from another airport or for another party is refused `multi_leg_not_supported` (ask for a price offer, §8). **Fields.** Required: `airport_code`, `resort_slug`, `pax` (at least 1), `date`. `date` is the airport's local day: it places a `flight_no` on its day, and when you also send a `flight_time` the two must name the same day **on the airport's clock** (otherwise `422 date_disagrees_with_flight_time` — a mistyped day is never booked silently); the same holds for `return_date` and `return_flight_time`. Optional: `luggage`, `trolley`, `ski` (whole numbers, default 0), `flight_no`, `flight_time`, `direction` (or `out_direction`: `arrival` default, or `departure`), `pickup_time`, `trip_type` / `round_trip`, `return_date`, `return_flight_no`, `return_flight_time`, `return_pickup_time`, `return_luggage`, `return_ski`, `return_service_type`, `supplements`. Codes are read in any case. ### Step 2b — Quote-first (ids, one service at a time) The same door also takes a body that names the journey by **ids** and a `service_type`. It answers `201` with a stored quote you then book by `quote_id` — useful when you want the price pinned: ```json { "airport_id": "…", "resort_id": "…", "service_type": "private", "pax": 2, "flight_no": "LY345", "date": "2026-12-17", "direction": "arrival" } ``` ```json { "quote_id": "…", "expires_at": "2026-12-17T09:56:23+00:00", "currency": "EUR", "options": [ { "key": "private:…", "service_type": "private", "shared_rail": null, "vehicle_class_name": "Van (up to 8)", "seats_required": 2, "meets_minimum": null, "on_request": false, "currency": "EUR", "gross_minor": 30000, "commission_bps": 1000, "net_minor": 27000, "bookable": true, "reason": null } ] } ``` `gross_minor` is the public fare, `net_minor` what you pay. `bookable: false` (with a `reason`) means your account cannot take that option (for instance the route is priced in another currency than your credit line). Which wire a request speaks is decided by its body alone: a body naming `airport_code` / `resort_slug` (and no id) is the flat wire; a body naming ids is quote-first. ### Step 3 — Create the booking Name the journey as in the quote, say the service, and send the price your quote showed: ```json { "service_type": "shared", "trip_type": "one_way", "airport_code": "GVA", "resort_slug": "val-thorens", "date": "2026-12-17", "pax": 2, "luggage": 2, "trolley": 2, "ski": 2, "flight_no": "LY345", "out_direction": "arrival", "price_total_cents": 16200, "settle": "credit", "client_ref": "crm-order-48213", "dropoff_address": "Hotel Alpaka, Val Thorens", "customer": { "name": "Dana Levi", "phone": "+972501234567", "email": "dana@example.com" } } ``` **The price you send is compared, never charged.** `price_total_cents` must equal the net the server derives now; the booking is always charged at the server's own price. If they differ nothing is written and you get `409 price_changed`, naming both figures — quote again and book at the price shown. A private trip's net can move between your quote and your booking for one more reason: when every vehicle of ours able to carry it is taken in its window in the meantime, its price carries a high-demand supplement, and it drops again when one is free: ```json { "error": "price_changed", "message": "The price changed since your quote; quote again and book at the price shown.", "language": "en", "context": { "field": "price_total_cents", "sent": 16200, "current": 17100, "currency": "EUR" } } ``` A booking is `201`: ```json { "ref": "WR-2026-00001", "booking_id": "…", "status": "confirmed", "price_total_cents": 16200, "currency": "EUR", "paid_by": "agent_credit", "tunnel_warning": null, "coach_driver_check": null } ``` `price_total_cents` is what the booking costs **you**. `tunnel_warning` (the route crosses a closed tunnel that day) and `coach_driver_check` (the driving-hours verdict for a coach or minibus) are advisory: the booking is made either way; both are `null` when they do not apply. **Fields.** Required: `service_type` (`shared` or `private`), `airport_code`, `resort_slug`, `date`, `pax`, `price_total_cents`, `customer`, and a time: `flight_no`, `flight_time` or `pickup_time` (a shared seat needs `flight_no` or `flight_time`). Optional: `trip_type`, `luggage`, `trolley`, `ski`, `out_direction` / `direction`, `pickup_time`, `chosen_class` (a private seat's vehicle class, by name or id, any case; the cheapest that fits when omitted; ignored for shared), `settle`, `client_ref`, `dropoff_address`, `dropoff_share_later`, `currency` (must be the route's), `supplements`, and the round-trip fields of Step 2 (a round trip travels in one class: `return_chosen_class`, when sent, equals `chosen_class`). `customer` is `{name, phone, email}`: a name, a phone **and** an email, all three required — every booking names both an email and a phone (since 2026-11-05). The phone is written with its country code (`+972 50 ...`; `050 ...` is refused). A missing or malformed one is `422` naming `customer.phone` or `customer.email`, with `reason` `phone_required`, `phone_invalid`, `email_required` or `email_invalid`. Anything else is refused by name. **The address is in the resort's price zone.** The resort is the price zone and the driver goes to the address: a `dropoff_address` (or a departure's `pickup_address`) more than 8 km from the resort the trip is priced for is refused `422` with `reason: "address_outside_resort_zone"`. Its `context.zone` says why, in English, French and Hebrew (`messages`), and what to do: `verdict: "reprice"` names the resort the address is in (`zone.resort`) — quote that resort instead; `verdict: "price_request"` means no resort we sell from that airport is within 8 km — send a price request (section 8). An address we cannot place on the map is accepted as before. A hotel partner's own address is its account's and is not judged. **Settlement (`settle`):** | Value | Meaning | Result | |---|---|---| | `credit` (default: your account's own setting) | Drawn from your credit line. Over the line, the booking is refused whole: `409 credit_limit_exceeded`, nothing written. | `paid_by: agent_credit` | | `card` | A pending card payment for your net. The booking waits (`quoted`; `on_request` where the vehicle is still to be arranged) until the payment is confirmed. | `paid_by: card`, plus `payment_id` and `payment_url` (the hosted page your client pays on) | | `approval` | Held for Winteride's approval (nothing is drawn until it approves). | `paid_by: pending_approval`, `status: awaiting_approval` | ```json { "ref": "WR-2026-00002", "booking_id": "…", "status": "quoted", "price_total_cents": 16200, "currency": "EUR", "paid_by": "card", "payment_id": "…", "payment_url": "https://pay.example/pay/…", "tunnel_warning": null, "coach_driver_check": null } ``` **Round trips:** `"trip_type": "round_trip"` with `return_flight_time` (or `return_flight_no` and `return_date`, or `return_pickup_time`); `price_total_cents` is the round trip's one price. > **Setting the resort pickup yourself.** On a **departure** leg — the way home, resort → airport — > the pickup happens at the resort hours before the flight, and for an early departure it falls on > the *previous day*. Omit it and the pickup is derived from the flight. To set your own, send an ISO > instant: `pickup_time` for a one-way resort → airport trip, `return_pickup_time` for the return of a > round trip. On an **arrival** leg the pickup defaults to the landing time. A **shared** seat's pickup > time is provisional: `pickup_time_final` on the voucher says when Winteride has locked it. #### Retrying safely (`client_ref` and `Idempotency-Key`) A network error or a timeout does not tell you whether the booking was made. Send your own key with every booking — `"client_ref": "your-order-id"` in the body, or an `Idempotency-Key` header (the body wins when both are sent; at most 80 characters, plain text, no line breaks) — and send the **same** key when you retry. The retry is answered with the booking you already have, **HTTP 200**, and nothing is created, held or charged: ```json { "id": "…", "ref": "WR-2026-00001", "status": "confirmed", "duplicate": true, "matched_on": "client_ref", "created_at": "2026-10-19T09:26:22+00:00", "message": "already booked as WR-2026-00001 - nothing new was created" } ``` Treat a `200` with `duplicate: true` as success and keep `ref`. A repeat is answered **before** the price is compared and before anything is quoted for a key you used before, so it is answered even if the price or the route has since moved. A key is yours alone (another partner can use the same one) and it keeps answering even after the booking is cancelled. Even **without** a key, the same traveller (an email, or a phone of at least 6 digits) on the same trip — airport, resort, direction, flight, service day on the airport's clock, party size — is answered the same way (`matched_on: "fingerprint"`) while that booking is not cancelled; a quote you re-send after its booking was made answers that booking too (`matched_on: "quote_id"`, same traveller only). Only the office can book a deliberate second identical trip; a `force` field in your request is refused `422 force_is_the_offices`. #### Booking from a stored quote (quote-first) Book the quote of Step 2b by its id and the option's key: ```json { "quote_id": "…", "option_key": "private:…", "contact": { "name": "Eli Bar", "phone": "+972502223344", "email": "eli@example.com" }, "settle": "credit", "client_ref": "qf-1" } ``` ```json { "id": "…", "ref": "WR-2026-00003", "status": "confirmed", "source": "partner_api", "trip_type": "one_way", "tz": "Europe/Zurich", "partner_settle": "credit", "created_at": "2026-10-19T09:26:23+00:00", "contact": { "name": "Eli Bar", "email": "eli@example.com", "phone": "+972502223344" }, "currency": "EUR", "gross_minor": 30000, "commission_bps": 1000, "net_minor": 27000, "charged_on_credit_minor": 27000, "legs": [ { "id": "…", "sequence_no": 1, "direction": "arrival", "service_type": "private", "from": "GVA", "to": "Val Thorens", "airport_code": "GVA", "resort": "Val Thorens", "pickup_address": null, "dropoff_address": null, "flight_no": "LY345", "flight_time": "2026-12-17T07:50:00+00:00", "pickup_time": "2026-12-17T07:50:00+00:00", "follow_flight_delays": true, "pax": 2, "luggage": 0, "ski": 0, "trolley": 0, "vehicle_class": "Van (up to 8)" } ], "cancel_preview": { "cancellable": true, "currency": "EUR", "fee_minor": 0, "credit_reversal_minor": 27000, "credit_fee_minor": 0, "refund_minor": 0 }, "settlement": { "debit_minor": 27000, "payment": null }, "tunnel_warning": null, "coach_driver_check": null } ``` The body carries the stored quote's `quote_id` and `option_key`, `contact`, `settle`, `client_ref` and optionally `flight_no`, `flight_time`, `dropoff_address`, `pickup_address`, `reason`. It does **not** take `price_total_cents`: the price is the quote's. `contact` is `{name, phone, email}`, all three required as for the flat body (`422` naming `contact.phone` or `contact.email`). ### Booking a group as named bookings (agents; when Winteride switches it on) `POST /group-bookings` books 2 to 20 shared seats as one real booking per traveller — each with its own drop-off, voucher target, return date and flight and its own cancellation — in one transaction on your credit line, priced as one party (six people in three rows cost the party-of-six fare). If any row cannot be booked nothing is booked and the answer names the row. Agents only (a hotel is refused); credit only. This door names the journey by **ids** (`airport_id`, `resort_id` from `/reference`). **A group is your order, so you are who we reach.** A row needs its traveller's name; its `phone` and `email` are optional. A row without them is booked with **your account's** mobile and email as its contact (the driver calls you, the messages come to you), and each row of the answer says which parts are yours in `contact_via_agent`. A phone or an email a row does give is kept and must be well formed (`422` naming the row otherwise). If a row gives none and your account has none either, the row is refused `422` (`phone_required` or `email_required`): add it to the row, or ask Winteride to add it to your account. ```json { "airport_id": "…", "resort_id": "…", "direction": "arrival", "flight_no": "LY345", "flight_time": "2026-12-17T07:50:00Z", "voucher_to": "passenger", "client_ref": "group-77", "rows": [ { "name": "Anna Weber", "phone": "+4479000001", "email": "anna@example.com", "pax": 2, "dropoff_address": "Hotel Alpaka", "return_date": "2026-12-24", "return_flight_no": "LY346" }, { "name": "Boris Kral", "pax": 2 } ] } ``` ```json { "group_ref": "WR-2026-00001", "pax": 4, "currency": "EUR", "total_minor": 42300, "charged_now_minor": 42300, "rows": [ { "row": 1, "id": "…", "ref": "WR-2026-00001", "name": "Anna Weber", "pax": 2, "status": "confirmed", "currency": "EUR", "gross_minor": 35000, "out_gross_minor": 17500, "return_gross_minor": 17500, "price_minor": 31500, "charged_now_minor": 31500, "returns": { "date": "2026-12-24", "flight_no": "LY346" }, "voucher_to": "passenger", "voucher_held_by_agent": false, "contact_via_agent": [] }, { "row": 2, "id": "…", "ref": "WR-2026-00002", "name": "Boris Kral", "pax": 2, "status": "confirmed", "currency": "EUR", "gross_minor": 12000, "out_gross_minor": 12000, "return_gross_minor": null, "price_minor": 10800, "charged_now_minor": 10800, "returns": null, "voucher_to": "passenger", "voucher_held_by_agent": false, "contact_via_agent": ["email", "phone"] } ] } ``` The price is the party price, not one fare per row: the first row pays the fare for its own size and each later row the difference, and a row can legitimately cost **0** once the party has reached the price of a private vehicle. `voucher_to` (`passenger`, the default, or `agent`) says who each row's voucher is written to. **Retrying:** send a group `client_ref` (or `Idempotency-Key`): the rows carry `#1` … `#N`, and sending it again returns the existing group — `200`, `duplicate: true`, nothing written. See `openapi.yaml`, `POST /group-bookings`, for every field. ### Step 4 — Read it, by reference or id ```bash curl https://$HOST/api/partner/v1/bookings/WR-2026-00001 -H "Authorization: Bearer $WINTERIDE_API_KEY" ``` Every per-booking path takes the booking's **reference** (the `ref` the booking answered with) **or** its `id`. You only ever see your own bookings: another partner's reference is a `404 not_found`, the same answer as a reference that does not exist — never a `403`. ```json { "id": "…", "ref": "WR-2026-00001", "status": "confirmed", "source": "partner_api", "trip_type": "one_way", "tz": "Europe/Zurich", "partner_settle": "credit", "created_at": "2026-10-19T09:26:22+00:00", "contact": { "name": "Dana Levi", "email": "dana@example.com", "phone": "+972501234567" }, "currency": "EUR", "gross_minor": 18000, "commission_bps": 1000, "net_minor": 16200, "charged_on_credit_minor": 16200, "legs": [ { "id": "…", "sequence_no": 1, "ticket_no": "WR-2026-00001-1", "direction": "arrival", "service_type": "shared", "from": "GVA", "to": "Val Thorens", "airport_code": "GVA", "resort": "Val Thorens", "pickup_address": null, "dropoff_address": null, "flight_no": "LY345", "flight_time": "2026-12-17T07:50:00+00:00", "pickup_time": "2026-12-17T07:50:00+00:00", "follow_flight_delays": true, "pax": 2, "luggage": 0, "ski": 0, "trolley": 0, "vehicle_class": null, "notices": [ { "code": "shared_seat", "title": "Shared transfer", "text": "A shared transfer costs less and is less flexible. The pickup time can change until the day before the trip, when we confirm it. Please check your email until then: we send any new time there." } ], "arrival_pickup": { "basis": "shared_van", "landing_time": "2026-12-17T07:50:00+00:00", "minutes_to_leave_airport": 75, "expected_pickup_time": "2026-12-17T09:05:00+00:00", "follows_flight": false, "title": "Meeting you at the airport", "text": "Your flight lands at 08:50. The shared van is expected to leave the airport at about 10:05, after the flights it waits for have landed." } } ], "cancel_preview": { "cancellable": true, "currency": "EUR", "fee_minor": 0, "credit_reversal_minor": 16200, "credit_fee_minor": 0, "refund_minor": 0 } } ``` Statuses: `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. The driver, once assigned, is on the voucher (Step 5), not a status. `gross_minor` is the public fare, `net_minor` what you pay (`charged_on_credit_minor` what your line was debited for it). `tz` is the zone the booking's pickup is read in, the local time the driver and the voucher show. `cancel_preview` is what cancelling **now** would do (recomputed on every read). `group_ref`, `group_seq` and `voucher_to` appear on a booking made in a group. Polling is the only status mechanism today (webhooks are planned, §9). **Each leg has its own ticket number** (`ticket_no`), like a flight ticket under its booking: the booking's reference and the leg's place, `WR-2026-00001-1` for the way out and `-2` for the way home. It is issued once and never re-used, and the voucher, our messages and the driver name the leg by it. A leg Winteride's office cancels on its own (the rest of the booking running) leaves your booking reads with its number; the booking's price and your credit follow, at the booking level. **A booking can hold more than a way out and a way home.** Your portal can add a leg to one of your bookings, and an accepted price offer can have several legs. Its `trip_type` then reads `multi_leg` on the booking read, the booking list and the voucher, and every leg is in `legs` with its own ticket number. Through this API you still book `one_way` or `round_trip`. `GET /bookings` lists your bookings, live first then by pickup, one page at a time: `limit` (at most 50) and `offset` in the query string. ```json { "total": 1, "limit": 50, "offset": 0, "bookings": [ { "id": "…", "ref": "WR-2026-00001", "status": "confirmed", "net_minor": 16200, "gross_minor": 18000, "legs": [], "contact": { "name": "Dana Levi" } } ] } ``` ### Step 5 — Voucher ```bash curl https://$HOST/api/partner/v1/bookings/WR-2026-00001/voucher -H "Authorization: Bearer $WINTERIDE_API_KEY" ``` ```json { "id": "…", "ref": "WR-2026-00001", "ref_full": "WR-2026-00001-A", "status": "confirmed", "trip_type": "one_way", "currency": "EUR", "total_minor": 18000, "tz": "Europe/Zurich", "is_last_minute": false, "contact": { "name": "Dana Levi", "email": "dana@example.com", "phone": "+972501234567" }, "legs": [ { "sequence_no": 1, "ticket_no": "WR-2026-00001-1", "direction": "arrival", "service_type": "shared", "from": "GVA", "to": "Val Thorens", "airport_code": "GVA", "airport_name": "Geneva", "resort": "Val Thorens", "flight_no": "LY345", "flight_time": "2026-12-17T07:50:00+00:00", "pickup_time": "2026-12-17T07:50:00+00:00", "pickup_time_final": false, "follow_flight_delays": true, "pickup_address": null, "pickup_address_pending": false, "dropoff_address": null, "pax": 2, "luggage": 0, "ski": 0, "trolley": 0, "vehicle": null, "driver": null, "supplements": [] } ], "tickets": [ { "sequence_no": 1, "ticket_no": "WR-2026-00001-1", "kind": "shared", "kind_words": "Shared transfer", "direction": "arrival", "ride_no": 1, "day": "2026-12-17", "band": "Arrival · Thu 17 Dec", "from": "Geneva", "to": "Val Thorens", "flight_no": "LY345", "flight_time": "2026-12-17T07:50:00+00:00", "pickup_at": "2026-12-17T07:50:00+00:00", "pickup_time_final": false, "van_leaves": false, "pickup_place": "Arrivals hall, Geneva", "pickup_address_pending": false, "pax": 2, "luggage": 0, "ski": 0, "party": "2 passengers, 0 bags", "vehicle": null, "extras": [], "facts": [ { "key": "flight", "label": "Flight lands", "value": "08:50", "sub": "LY345" } ], "details": [ { "key": "party", "label": "Party", "value": "2 passengers, 0 bags" } ] } ] } ``` The voucher is the customer-facing view (legs, pickup times, the driver once assigned, addresses), and since 1.17.0 its `tickets`, one per ride, drawn as the traveller's voucher draws them, and each leg's `pickup_address_pending` (a departure whose pickup address is still to follow). Since 1.20.0 a **shared** leg also carries `notices` (the same `Notice` as the quote's `shared`), here and on the leg of `GET /bookings/{ref}`; a private leg has no `notices` key. Show it where you show the leg's pickup time. Since 1.21.0 an **arrival** leg whose landing we know carries `arrival_pickup` (when we expect to meet the passenger: the landing, the minutes to leave the airport, the expected pickup, and the words; see the changelog), here and on `GET /bookings/{ref}`. A booking parked for approval, or cancelled, has none: `409 voucher_not_issued`. On confirmation Winteride sends the voucher by email and WhatsApp to **you**, on the contacts held on your partner profile, in your chosen language, so you hold your client's voucher yourself. (Every booking names your traveller's email and phone, or, on a group row that gave none, yours; the driver reaches them on the phone.) **Your traveller hears from us later**: only once the first leg is within the platform's quiet window (`agent_client_quiet_hours`, 48 hours unless Winteride has set another); a booking whose voucher you hold (`voucher_to: agent`) is never written to by us. > **Planned / not yet available:** a public shareable `voucher_url` link. --- ## Amending & cancelling (from the guide) Amendments change a booking's **legs**. Name each leg by its `id` (from the booking) and send only the fields you want to change: `pickup_time`, `pax`, `luggage`, `ski`, `vehicle_class_id`, `trolley`, `flight_no`, `flight_time`, `dropoff_address`, `pickup_address` (a hotel's addresses are its account's and are refused). Anything else — the van a shared leg rides, the office's pickup lock, a typed price — is refused by name. A new address more than 8 km from the leg's resort is refused like a booking's (`422 address_outside_resort_zone`, step 3). Preview first, then commit the **delta the preview showed**: ```json { "legs": [ { "leg_id": "…", "pax": 3 } ] } ``` ```json { "booking_id": "…", "ref": "WR-2026-00001", "status": "confirmed", "status_after": "confirmed", "currency": "EUR", "can_confirm": true, "capacity_ok": true, "no_change": false, "price": { "delta_minor": 7500, "total_before_minor": 18000, "total_after_minor": 25500, "version_no": 1, "writes_new_version": true }, "legs": [ { "leg_id": "…", "sequence_no": 1, "service_type": "shared", "changes": { "pax": { "from": 2, "to": 3 } }, "price": { "before_minor": 18000, "after_minor": 25500, "delta_minor": 7500, "repriced": true } } ], "settlement": { "settle_method": "credit", "credit_debit_minor": 6800, "credit_refund_minor": 0, "within_limit": true, "partner_active": true, "partner_refusal": null } } ``` `price.delta_minor` is the change in the **public** fare; `settlement.credit_debit_minor` is what your line is debited (your net of it). `can_confirm: false` says why in `settlement.partner_refusal` (for instance a rise on a card booking cannot be collected). Commit with the same `legs` and the delta you were shown; any other figure is `409 amendment_price_changed`, and an omitted one is `422`: ```json { "legs": [ { "leg_id": "…", "pax": 3 } ], "expected_delta_minor": 7500 } ``` ```json { "booking_id": "…", "ref": "WR-2026-00001", "status": "confirmed", "legs": [ { "leg_id": "…", "changes": { "pax": { "from": 2, "to": 3 } } } ], "price": { "delta_minor": 7500, "total_minor": 25500, "version_no": 2, "wrote_new_version": true, "price_version_id": "…" }, "settlement": { "settle_method": "credit", "delta_minor": 7500, "credit_debit_minor": 6800, "credit_refund_minor": 0, "refund_minor": 0, "currency": "EUR" }, "seats": [ { "leg_id": "…", "run_id": "…", "seats_delta": 1 } ], "audit_event_id": "…" } ``` **Cancel:** `POST /bookings/{ref}/cancel`. The body may carry a `reason` (text) and nothing else — the office's own options (a fee override, a no-show) are refused by name. ```json { "reason": "plans changed" } ``` ```json { "id": "…", "ref": "WR-2026-00001", "status": "cancelled", "source": "partner_api", "trip_type": "one_way", "currency": "EUR", "gross_minor": 25500, "net_minor": 23000, "charged_on_credit_minor": 0, "cancellation": { "refund_minor": 0, "credit_reversal_minor": 23000, "credit_fee_minor": 0 } } ``` The answer is the cancelled booking (as in Step 4) plus `cancellation`: `credit_reversal_minor` is given back to your credit line, `credit_fee_minor` is the fee kept, and `refund_minor` is what goes back to a card (0 on credit). ### Cancellation terms What a cancellation costs depends on how long before the flight of that leg it is made, and partner bookings are judged on the **partner ladder in your agreement** with Winteride — which is not published on the website. **Read it from your own booking rather than hard-coding it:** `cancel_preview` on every booking read (and on every list row) is what cancelling now would do, from the same function that executes the cancellation. The public terms at `GET /api/public/terms` are the **customer** ladder; they do not describe your account. > **Payment terms** — deposits and balance dates are for direct clients only. You book against your > credit line and settle on account. ## Other doors (from the guide) ### Flight lookup `GET /flights/lookup?flight_no=LY345&date=2026-12-17` (optional `direction=arrival|departure`, `airport_code`) answers the facts the quote uses for a flight number. Sixty a minute per address; over that is `429 rate_limited`. ```json { "flight_no": "LY345", "date": "2026-12-17", "direction": "arrival", "airport_code": null, "flight_airport": "GVA", "found": true, "time": "2026-12-17T07:50:00+00:00", "operates_on_date": true, "is_tlv_direct": true, "in_seasonal_list": true, "shared_possible": true, "manual_entry_allowed": false, "reason": "ok", "source": "seasonal", "provider": "mock", "provider_status": "no_answer" } ``` ### Stop sale — what not to sell (when Winteride switches it on) If you sell our transfers unattended from a price list, you need to know when we cannot cover a date before you sell it, not after. `GET /stop-sale?from=YYYY-MM-DD&to=YYYY-MM-DD` answers **your own** picture (a range of at most 62 days; today and the platform's horizon by default; thirty a minute per address): ```json { "from": "2026-10-20", "to": "2026-10-20", "reserve": 3, "windows": [ { "service_date": "2026-10-20", "starts_at": "2026-10-19T22:00:00+00:00", "ends_at": "2026-10-20T22:00:00+00:00", "free_vans": 3 } ] } ``` Each window is closed **for your account**. The threshold is set per partner, so you may be stopped while some capacity still exists: `reserve` is how many vehicles are held back from your account before a window closes, and `free_vans` is how many were left at the tightest moment of it (`0` means the fleet was genuinely full). An empty `windows` list means nothing is closed in the range. The list is refreshed continuously; it is not a reservation, and a booking is still only confirmed when the booking call says it is. Your partner portal shows the same list, and Winteride can e-mail you when a window opens or clears (the office is copied on that e-mail). **A booking in a closed window is taken on request (since 1.22.0).** While stop sale is on, a booking with a leg whose pickup falls in one of your closed windows is still taken: the answer is `201`, the booking's `status` is `on_request`, and it carries `awaiting_confirmation`: ```text "status": "on_request", "awaiting_confirmation": { "reason": "stop_sale", "message": "We have received this booking and it waits for our confirmation: our own vans are on stop sale at this time. No voucher is issued until we confirm it. We will write to you as soon as it is confirmed." } ``` No vehicle is placed, nothing is charged on your credit line (a card sale opens an authorise-only page) and no voucher is issued: the voucher doors answer `409 voucher_not_issued`. Our office then confirms the booking (it becomes `confirmed`, the key is gone, the voucher is issued) or declines it (it becomes `cancelled`; nothing was charged). Read the booking again to learn the outcome. `message` is in the language you asked for; show it to your user. **A booking in a closed window is refused (since 1.18.0, only when Winteride has switched refusals on).** A booking with a leg whose pickup falls in one of your closed windows is answered `409 stop_sale`. Nothing is held, charged or created. A quote is never refused, so you can still see the price. The refusal names every refused leg in `context.legs`, and the window, the count and the reserve are the very ones this list shows (shortened; the real answer carries the full sentences): ```text { "error": "stop_sale", "message": "We cannot take this booking: sales to your account are stopped from 2026-12-19 08:00 until 2026-12-19 18:00 (Europe/Paris). Our free vans (1) are down to the reserve held back from you (2). Please contact the office.", "language": "en", "context": { "override_possible": false, "legs": [ { "sequence_no": 1, "pickup_time": "2026-12-19T09:00:00+00:00", "window": { "from": "2026-12-19T08:00:00+01:00", "until": "2026-12-19T18:00:00+01:00", "zone": "Europe/Paris", "from_utc": "2026-12-19T07:00:00+00:00", "until_utc": "2026-12-19T17:00:00+00:00", "service_date": "2026-12-19", "open_started": false, "open_ended": false }, "free_vans": 1, "reserve": 2, "messages": { "en": "We cannot take this booking: …", "he": "לא ניתן לקבל את ההזמנה הזו: …", "fr": "Nous ne pouvons pas prendre cette réservation : …" } } ] } } ``` `message` is in the language you asked for (`Accept-Language`); `messages` carries all three. `open_started` or `open_ended` is `true` when the closure may begin earlier or end later than the window shown. Branch on `error`, not on the words. Sell outside the window, or contact the office: only Winteride's office can book through a closed window. ### Booking from a Google Sheet (when Winteride switches it on) Agents who work from a spreadsheet can book from it. This is a separate, optional channel with its own **sheet key** (created by you in your portal, shown once, expiring, revocable — never your session token and never a password) and four paths under `/api/partner/v1/sheet`: `GET /columns`, `POST /check`, `POST /import`, `GET /history` (see `openapi.yaml`, tag *Sheet*). A sheet key opens these four paths and nothing else, and your session token does not open them. A row is read strictly (no default direction or service; dates `YYYY-MM-DD` or `DD/MM/YYYY`; whole-number counts), a checked row writes nothing, a booked row is locked for good, and a card payment is not offered. The ready-made Apps Script and its guide are in `docs/integrations/google-sheets/`. ## Safe-retry summary (from the guide) | You send | A repeat is answered | |---|---| | a booking with `client_ref` / `Idempotency-Key` | `200`, `duplicate: true`, `matched_on: client_ref` | | the same traveller on the same trip, no key | `200`, `matched_on: fingerprint` | | a stored quote you already booked | `200`, `matched_on: quote_id` | | a group with a key | `200`, `duplicate: true`, `matched_on: client_ref` (the existing group) | ## Price offers — on-request and custom routes (from the guide) When the automatic engine can't price it (free-text addresses, unusual parties, special requests), ask for a price. You never type a price: Winteride prices the request and sends you a link. ```json { "from_label": "Chamonix centre", "to_label": "Résidence Les Alpages, Val Thorens", "date": "2026-12-17", "pax": 6, "notes": "2 wheelchairs", "customer": { "name": "Group Cohen", "phone": "+972502223344", "email": "g@example.com" } } ``` ```json { "ref": "WO-2026-00001", "status": "requested" } ``` Allowed fields: `from_label`, `to_label` (or `airport_id` / `resort_id`), `date`, `pickup_time`, `flight_no`, `direction`, `pax`, `luggage`, `ski`, `trolley`, `round_trip`, `return_date`, `return_pickup_time`, `return_flight_no`, `customer`, `notes`; any other field is refused. Once Winteride has priced it, read it by the **token in the link it sends you** (`GET /offers/{token}`; a bad token, another partner's offer and a bare `WO-` reference are all one `404`) and accept it with an empty body: ```json { "ref": "WO-2026-00001", "status": "sent", "valid_until": "2026-10-26T09:00:00+00:00", "currency": "EUR", "total_minor": 30000, "customer": { "name": "Group Cohen", "phone": "+972502223344", "email": "g@example.com" }, "legs": [ { "sequence_no": 1, "direction": "arrival", "service_type": "private", "from": "Chamonix centre", "to": "Les Alpages", "service_date": "2026-12-17", "pickup_time": "2026-12-17T07:50:00+00:00", "flight_no": null, "flight_time": null, "pax": 6, "luggage": 0, "ski": 0, "vehicle": null, "price_minor": 30000 } ], "booking_ref": null, "client_note": null, "client_submitted": false } ``` ```json { "offer_ref": "WO-2026-00001", "booking_id": "…", "booking_ref": "WR-2026-00004", "status": "confirmed" } ``` `POST /offers/{token}/accept` is `201`; the booking is yours (read it by `booking_ref`). An offer that expired, was closed or was already accepted says why (`409`, `context.reason`). ## AI agents: llms.txt and the MCP connector (from the guide) **Feeding an agent the API.** [`llms.txt`](./llms.txt) is this guide's rules and the contract's every door — fields, an example, the answers and the errors — in one plain-text file, generated from the contract and this guide so it says what the API does. Give it to the agent with your API key. **The MCP connector (when Winteride switches it on).** An agent that speaks the Model Context Protocol connects to `POST /api/partner/v1/mcp` (Streamable HTTP, JSON answers) with your API key as its bearer token — a session token is refused there. It speaks the current revision (`2026-07-28`: every request carries its protocol version and capabilities in `params._meta`, mirrored in the `MCP-Protocol-Version`, `Mcp-Method` and `Mcp-Name` headers) and the earlier `initialize` handshake (`2025-11-25`, `2025-06-18`, `2025-03-26`). Its tools: | Tool | The door it runs | |---|---| | `search_routes_and_resorts` | `GET /reference` and the routes we sell (codes, no prices) | | `get_quote` | `POST /quotes`, the flat wire | | `create_booking` | `POST /bookings`, the flat wire; `idempotency_key` is **required** and sent as `Idempotency-Key` | | `list_bookings`, `get_booking` | `GET /bookings`, `GET /bookings/{ref}` | | `preview_amendment`, `amend_booking` | `POST /bookings/{ref}/amend/preview`, `/amend` | | `cancel_booking` | `POST /bookings/{ref}/cancel` | | `lookup_flight` | `GET /flights/lookup` | | `get_voucher` | `GET /bookings/{ref}/voucher` | Each tool **is** that door: the same prices, checks and money rules, the same booking. A door's refusal is the tool's error result (`isError: true`) carrying this API's error envelope and its status, so an agent reads `price_changed` and quotes again. The three tools that change money say so; a well-behaved agent asks its human first. One JSON-RPC message per POST (a batch is refused); a request from a browser (an `Origin` header) is `403`; sixty calls a minute per key. It lists its tools like this: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } } ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "resultType": "complete", "tools": [ { "name": "search_routes_and_resorts", "title": "Search routes and resorts", "description": "…", "inputSchema": { "type": "object" }, "annotations": { "readOnlyHint": true } } ], "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "winteride-partner", "version": "1.22.0" } } } } ``` (sent with the headers `MCP-Protocol-Version: 2026-07-28` and `Mcp-Method: tools/list`). The public `/mcp` connector on our website is another thing: anyone's, read-only, with no account behind it. ## Errors & status codes (from the guide) | Status | `error` | Meaning | |---|---|---| | `401` | `authentication_required` | No, expired, wrong, rotated or revoked key or token (or a sheet key where an API key is needed). | | `401` | `sign_in_refused` | The sign-in code is wrong, expired or already used; ask for a new one. | | `403` | `forbidden` | Signed in, but this door is not yours (for instance a hotel on an agent-only door). | | `404` | `not_found` | Not found, **or not yours**, or a door that is switched off. Never a `403` for a booking that is another partner's. | | `409` | `price_changed` | `price_total_cents` is not the net the server derives now. | | `409` | `credit_limit_exceeded` | The booking would exceed your credit line; nothing was written. | | `409` | `amendment_price_changed` | The `expected_delta_minor` is not the delta derived now. | | `409` | `capacity_exceeded` | Nothing is free to carry this journey. | | `409` | `stop_sale` | A leg's pickup is in a window closed to your account (our free vans are at or below the reserve held back from you); `context.legs` names the window, the free vans and the reserve. Nothing was held or charged. Contact the office. | | `409` | `illegal_state_transition` | The booking's state does not allow it (for instance cancelling a booking that is already cancelled). | | `409` | `voucher_not_issued` | A cancelled booking, one held for approval, or one taken on request in a stop-sale window and not confirmed yet (`awaiting_confirmation`) has no voucher. | | `422` | `validation_error` | The request is wrong: `context` names the field (`field` / `fields` / `missing`) and often the allowed values. | | `429` | `rate_limited` | Too many calls for your key, or from one address on the doors that count so (sign-in, flight lookup, stop sale); retry after the `Retry-After` header. | | `429` | `too_many_attempts` | Three wrong tries spent the sign-in code; ask for a new one. | ## Rate limits (from the guide) Every call made with an API key counts against **that key**: 120 a minute (and the MCP connector 60 a minute) unless Winteride has set another. Some doors also count **per address**: sign-in codes ten every 10 minutes, `GET /flights/lookup` 60 a minute, `GET /stop-sale` 30 a minute. Please be a good citizen: cache `/reference`, avoid tight polling loops, and one booking per request. Design defensively: a `429` carries `Retry-After`. Every call made with a key is recorded against it (when, which door, the answer's status), and the portal shows when each key was last used. ## Every operation (from the contract) Paths are relative to the base URL. `PartnerApiKey` is `Authorization: Bearer wrp_...`; `SessionToken` is a signed-in session's bearer (the same partner, for trying the API by hand); `SheetKeyAuth` is the Google-Sheet channel's own key. ### GET /me — Your partner profile operationId: getMe. Credential: PartnerApiKey or SessionToken. Who you are to us, your terms, your credit position and the language we send your documents in. Answers: - 200 -> PartnerProfile: Your profile - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) Answer fields (200): - user_id: string, REQUIRED - kind: string (agent, hotel), REQUIRED - legal_name: string or null, REQUIRED - contact_name: string or null, REQUIRED - display_name: string or null, REQUIRED - email: string or null, REQUIRED - language: string (en, he, fr, None) or null, REQUIRED — null: decided from your phone number - settle_default: string (credit, card, None) or null, REQUIRED — the rail a booking uses when it names none - terms: object or null, REQUIRED - commission_bps: integer, REQUIRED — your rate on private transfers, in basis points (1000 = 10 %) - commission_bps_shared: integer or null, REQUIRED — your rate on shared seats; null = the same as private - credit_limit_minor: integer, REQUIRED - settlement_currency: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - credit: object or null, REQUIRED - balance_minor: integer, REQUIRED — negative = drawn down - limit_minor: integer, REQUIRED - available_minor: integer, REQUIRED — limit + balance - currency: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - home_resort: object or null — A hotel's own resort. - id: string - name: string - street_address: string or null — A hotel's own street address. (No other field: an unknown one is refused 422 by name.) ### PATCH /me — Set the language you receive documents in operationId: updateMe. Credential: PartnerApiKey or SessionToken. Sets `language` for every voucher, price offer and notification we send you: `en`, `he`, `fr`, or `null` to go back to deciding from your phone number. Nothing else can be changed here; any other key is refused `422` by name. Body fields: - language: string (en, he, fr, None) or null, REQUIRED (No other field: an unknown one is refused 422 by name.) Example body: {"language": "fr"} Answers: - 200 -> PartnerProfile: Your updated profile - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (200): - user_id: string, REQUIRED - kind: string (agent, hotel), REQUIRED - legal_name: string or null, REQUIRED - contact_name: string or null, REQUIRED - display_name: string or null, REQUIRED - email: string or null, REQUIRED - language: string (en, he, fr, None) or null, REQUIRED — null: decided from your phone number - settle_default: string (credit, card, None) or null, REQUIRED — the rail a booking uses when it names none - terms: object or null, REQUIRED - commission_bps: integer, REQUIRED — your rate on private transfers, in basis points (1000 = 10 %) - commission_bps_shared: integer or null, REQUIRED — your rate on shared seats; null = the same as private - credit_limit_minor: integer, REQUIRED - settlement_currency: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - credit: object or null, REQUIRED - balance_minor: integer, REQUIRED — negative = drawn down - limit_minor: integer, REQUIRED - available_minor: integer, REQUIRED — limit + balance - currency: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - home_resort: object or null — A hotel's own resort. - id: string - name: string - street_address: string or null — A hotel's own street address. (No other field: an unknown one is refused 422 by name.) ### GET /reference — List airports, resorts and vehicle classes operationId: getReference. Credential: PartnerApiKey or SessionToken. Static reference data for building quotes and bookings. The flat doors take `airports[].code` and `resorts[].slug`; the quote-first doors take the `id`s. A row never carries a price. Safe to cache for a few hours. **Planned / not yet available:** a `route_map` of airport to reachable resorts. Answers: - 200 -> Reference: Reference data - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) Answer fields (200): - airports: array of object, REQUIRED - id: string, REQUIRED - code: string, REQUIRED - name: string, REQUIRED - country: string or null, REQUIRED - allows_shared: boolean, REQUIRED (No other field: an unknown one is refused 422 by name.) - resorts: array of object, REQUIRED - id: string, REQUIRED - slug: string, REQUIRED - name: string, REQUIRED - country: string or null, REQUIRED - allows_shared: boolean, REQUIRED (No other field: an unknown one is refused 422 by name.) - vehicle_classes: array of object, REQUIRED - id: string, REQUIRED - name: string, REQUIRED - max_pax: integer, REQUIRED - max_luggage: integer, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) ### GET /flights/lookup — Look up a flight's scheduled time operationId: lookupFlight. Credential: PartnerApiKey or SessionToken. The facts the quote uses for a flight number: whether we know it, its time on that day, whether a shared seat is possible. Sixty a minute per address (`429 rate_limited` above). Parameters: - flight_no (in query): string, REQUIRED - date (in query): string, date, REQUIRED - direction (in query): string (arrival, departure) - airport_code (in query): string Answers: - 200 -> FlightLookup: Flight facts - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values - 429 -> Error: Too many calls for your key, or from one address on the doors that say so (`rate_limited`); retry after the `Retry-After` header Answer fields (200): (FlightLookup) The public lookup's facts; further detail fields may appear. - flight_no: string, REQUIRED - date: string, date, REQUIRED - direction: string (arrival, departure), REQUIRED - airport_code: string or null - flight_airport: string or null - found: boolean, REQUIRED - time: string, date-time or null, REQUIRED - operates_on_date: boolean or null, REQUIRED - is_tlv_direct: boolean - in_seasonal_list: boolean - shared_possible: boolean - manual_entry_allowed: boolean - reason: string, REQUIRED - source: string or null, REQUIRED — seasonal | live | null - provider: string or null - provider_status: string ### POST /quotes — Price a transfer operationId: createQuote. Credential: PartnerApiKey or SessionToken. **Flat wire** (a body naming `airport_code` / `resort_slug`): prices **both** services — the shared seat and every private vehicle that fits — and answers `200` with `shared` and `private[]`, every price your **net**. **To get a shared price you must send `flight_no` or `flight_time`.** A shared seat is pooled on a landing time; without one `shared` is `available: false` with `reason: "no_flight_time"` and a `hint`, no matter how eligible the route is. Private prices are returned either way (priced as of midday of the day when no time is given). **Quote-first wire** (a body naming `airport_id` / `resort_id` and a `service_type`): one service per quote, stored, answered `201` with a `quote_id` you book by id (`POST /bookings` with `quote_id` and `option_key`). Body fields: One of — FlatQuoteRequest: - airport_code: string, REQUIRED — IATA code, any case - resort_slug: string, REQUIRED - pax: integer, REQUIRED [min 1] - date: string, date, REQUIRED — the airport's local day; with a flight_time, the two must name the same day on the airport's clock (422 date_disagrees_with_flight_time) - luggage: integer [min 0; default 0] — checked suitcases - trolley: integer [min 0; default 0] — cabin bags: carried for the driver, never priced - ski: integer [min 0; default 0] — ski / snowboard sets - flight_no: string - flight_time: string, date-time — The landing time (the departure time on a `departure` leg), ISO 8601, when there is no flight number. A shared seat needs `flight_no` or `flight_time`. - direction: string (arrival, departure) [default "arrival"] - out_direction: string (arrival, departure) — the same as `direction` - pickup_time: string, date-time — the resort pickup, when you set it yourself - round_trip: boolean [default false] - trip_type: string (one_way, round_trip) [default "one_way"] - return_date: string, date - return_flight_no: string - return_flight_time: string, date-time - return_pickup_time: string, date-time - return_luggage: integer [min 0] — defaults to the outbound's - return_ski: integer [min 0] — defaults to the outbound's - return_trolley: integer [min 0] — must equal `trolley`: cabin bags travel with the whole journey - return_service_type: string (shared, private) - return_airport_code: string — must be the same airport: another is `multi_leg_not_supported` - return_pax: integer [min 1] — must be the same party - supplements: array of object — Catalogue extras to price in (`FlatQuoteResponse.supplements`). - id: string - qty: integer [min 1] (No other field: an unknown one is refused 422 by name.) One of — QuoteFirstRequest: (QuoteFirstRequest) The journey by ids and one service; the other fields are the flat quote's (`flight_no`, `flight_time`, `date`, `direction`, the return fields, `supplements`). - airport_id: string, REQUIRED - resort_id: string, REQUIRED - service_type: string (shared, private), REQUIRED - pax: integer, REQUIRED [min 1] - luggage: integer - ski: integer - trolley: integer - direction: string (arrival, departure) - flight_no: string - flight_time: string, date-time - pickup_time: string, date-time - date: string, date - discount_code: string — judged and reported `partner_sale`: nothing is taken off a partner's net Example body: {"airport_code": "GVA", "resort_slug": "val-thorens", "pax": 2, "date": "2026-12-17", "luggage": 2, "trolley": 2, "ski": 2, "flight_no": "LY345", "direction": "arrival"} Answers: - 200 -> FlatQuoteResponse: The flat quote (both services) - 201 -> QuoteFirstResponse: The stored quote-first quote (one service) - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (200): (FlatQuoteResponse) Every price is YOUR net (the public fare less your commission, rounded up to the whole euro), the figure a booking then charges. Read `shared.available`, not `shared.eligible`. - in_season: boolean, REQUIRED — true on every quote returned: a date no pricing period covers is a 404 - season_tier: string or null, REQUIRED - season_period: string or null, REQUIRED - flight: object, REQUIRED - flight_no: string - found: boolean, REQUIRED — the flight's time came from our timetable or the live feed - time: string, date-time or null (No other field: an unknown one is refused 422 by name.) - travel: object or null, REQUIRED — always null today: the Partner API carries no road estimate - private: array of object, REQUIRED — One entry per vehicle class that fits the party and can be booked on your account, cheapest first. - class: string or null, REQUIRED - vehicle_class_id: string, REQUIRED - max_pax: integer or null, REQUIRED - max_luggage: integer or null, REQUIRED - vehicles: integer — only on a multi-vehicle option - on_request: boolean, REQUIRED — not confirmed automatically: booked on request - price_cents: integer, REQUIRED — your net - currency: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - shared: object, REQUIRED - available: boolean, REQUIRED - price_cents: integer — your net (or the price agreed with you for this route and party) - currency: string - seats_remaining: integer or null — free seats on the matching van now; null while no van is scheduled - on_request: boolean — the route's minimum party is not met yet: bookable, confirms once enough join - notices: array of Notice — 1.20.0: on an available shared seat, what a shared seat is: it costs less and is less flexible, and its pickup time can change until the day before the trip (see `Notice`). Show it wherever you show the seat. Absent on a seat that is not offered. - code: string, REQUIRED — stable; the kind of notice - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - reason: string (no_flight_time, flight_time_unknown, below_min, shared_group_too_large, shared_luggage_limit, shared_closed_off_season, not_tlv_or_near_tlv, general_shared_no_price, flight_not_listed, flight_wrong_airport, flight_not_operating_on_date, shared_pickup_off_its_flight, airport_not_shared, resort_not_shared, route_currency_not_settlement_currency, not_available) — Why a shared seat is not offered. - hint: string or null — a sentence saying why and what to change (No other field: an unknown one is refused 422 by name.) - supplements: array of object, REQUIRED - id: string, REQUIRED - name: string, REQUIRED - price_cents: integer, REQUIRED (No other field: an unknown one is refused 422 by name.) - supplements_ignored: array of object — Only on a quote that sent `supplements`. Each asked id the engine could not price; a booking asking for one is refused `422 supplement_not_priced`. - id: string, REQUIRED - reason: string (unknown, inactive, not_extra, other_currency), REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) Answer fields (201): - quote_id: string, REQUIRED - expires_at: string, date-time, REQUIRED - currency: string, REQUIRED - options: array of object, REQUIRED - key: string, REQUIRED — book it with `option_key` - service_type: string (shared, private, mixed), REQUIRED - shared_rail: string or null - vehicle_class_name: string or null - seats_required: integer or null - meets_minimum: boolean or null - on_request: boolean, REQUIRED - currency: string, REQUIRED - gross_minor: integer, REQUIRED — the public fare - commission_bps: integer, REQUIRED - net_minor: integer, REQUIRED — what you pay - bookable: boolean, REQUIRED — false: your account cannot take this option (see `reason`) - reason: string or null, REQUIRED - arrival_pickup: ArrivalPickup — 1.21.0: only on an ARRIVAL leg whose landing Winteride knows (a time you or your client gave, the flight list's, or the flight feed's): when we expect to meet the passenger. The leg's `pickup_time` stays the landing; this says the landing, the minutes it takes to leave the airport (passport control and baggage) and the expected pickup, each as its own field, and the words to show your client. Absent on every other leg. - basis: string (landing, stated, shared_van), REQUIRED — `landing`: a pickup derived from the flight (the landing plus the minutes); `stated`: a pickup that was chosen (shown as it is, nothing recalculated); `shared_van`: a shared seat, whose van leaves after the flights it waits for - landing_time: string, date-time, REQUIRED — the flight's landing, as Winteride holds it - minutes_to_leave_airport: integer or null, REQUIRED — minutes from the landing to the expected pickup; null on a stated pickup - expected_pickup_time: string, date-time, REQUIRED — when we expect to meet the passenger (a shared van: when it is expected to leave the airport) - follows_flight: boolean, REQUIRED — true when a late flight moves the pickup, and with it this time - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) ### POST /quote-requests — Request an on-request / custom-route price operationId: createQuoteRequest. Credential: PartnerApiKey or SessionToken. For routes or requests the automatic engine can't price (free-text addresses, unusual parties, special requests). Creates a `WO-` offer in `requested`; Winteride prices it and sends you a link. You never type a price: a field outside the allowed ones — a price, a partner, a status — is refused `422` by name. Body fields: (PriceRequest) Provide a coded airport and resort (by id) or free-text labels, a date, a party and a way to reach the traveller. - from_label: string - to_label: string - airport_id: string - resort_id: string - date: string, date, REQUIRED - pickup_time: string, date-time - flight_no: string - direction: string (arrival, departure) - pax: integer, REQUIRED [min 1] - luggage: integer [min 0] - ski: integer [min 0] - trolley: integer [min 0] - round_trip: boolean - return_date: string, date - return_pickup_time: string, date-time - return_flight_no: string - customer: object, REQUIRED — The traveller; a name and a phone or an email to send the price to. The offer it becomes is sent and booked only once it carries both an email and a phone (every booking names both, since 2026-11-05). - name: string - surname: string - phone: string - email: string - notes: string [max length 2000] (No other field: an unknown one is refused 422 by name.) Answers: - 201 -> PriceRequestCreated: The request was stored - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (201): - ref: string, REQUIRED - status: string (requested), REQUIRED (No other field: an unknown one is refused 422 by name.) ### GET /offers/{token} — Read your offer by the token in the link it was sent with operationId: getOffer. Credential: PartnerApiKey or SessionToken. A bad token, another partner's offer and a bare `WO-` reference are all one `404` with no context. Parameters: - token (in path): string, REQUIRED Answers: - 200 -> Offer: The offer - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) Answer fields (200): - ref: string, REQUIRED - status: string (sent, accepted), REQUIRED - valid_until: string, date-time or null, REQUIRED - currency: string, REQUIRED - total_minor: integer, REQUIRED — the offer's price (gross, as the office priced it) - customer: object, REQUIRED - name: string or null - surname: string or null - email: string or null - phone: string or null - accommodation: string or null - dropoff_address: string or null (No other field: an unknown one is refused 422 by name.) - legs: array of object, REQUIRED - sequence_no: integer - direction: string (arrival, departure) - service_type: string (shared, private) - from: string or null - to: string or null - service_date: string, date - pickup_time: string, date-time or null - flight_no: string or null - flight_time: string, date-time or null - pax: integer - luggage: integer - ski: integer - vehicle: string or null - price_minor: integer or null (No other field: an unknown one is refused 422 by name.) - booking_ref: string or null, REQUIRED — the booking it became, once accepted - client_note: string or null, REQUIRED - client_submitted: boolean, REQUIRED (No other field: an unknown one is refused 422 by name.) ### POST /offers/{token}/accept — Accept a priced offer — it becomes your booking operationId: acceptOffer. Credential: PartnerApiKey or SessionToken. The body is empty. The booking is yours, on your account (read it by `booking_ref`). An offer that expired, was closed, is not ready or was already accepted says why: `409`, `context.reason` (`offer_expired`, `offer_closed`, `offer_not_ready`, `offer_already_accepted`). Parameters: - token (in path): string, REQUIRED Answers: - 201 -> OfferAccepted: Accepted; the booking was created - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 409 -> Error: A refusal of the act in the booking's or the line's current state (`error` names it) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (201): - offer_ref: string, REQUIRED - booking_id: string, REQUIRED - booking_ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. (No other field: an unknown one is refused 422 by name.) ### GET /bookings — List your bookings operationId: listBookings. Credential: PartnerApiKey or SessionToken. Your bookings, live first then by pickup, one page at a time (`limit` at most 50, `offset`). Each row is the booking as `GET /bookings/{ref}` shows it, with its live `cancel_preview`. Parameters: - limit (in query): integer - offset (in query): integer Answers: - 200 -> BookingPage: One page of bookings - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (200): - total: integer, REQUIRED - limit: integer, REQUIRED - offset: integer, REQUIRED - bookings: array of Booking, REQUIRED - id: string, REQUIRED - ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - source: string, REQUIRED - trip_type: string (one_way, round_trip, multi_leg), REQUIRED — multi_leg: a trip of more legs than a way out and a way home (a leg added to the booking, or a price offer of several legs) - tz: string — the zone this booking's pickup is read in: what the driver and the voucher show - partner_settle: string (credit, card, approval, None) or null, REQUIRED - created_at: string, date-time, REQUIRED - contact: object, REQUIRED - name: string or null, REQUIRED - email: string or null, REQUIRED - phone: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - legs: array of BookingLeg, REQUIRED - id: string, REQUIRED — the `leg_id` an amendment names - sequence_no: integer, REQUIRED - ticket_no: string or null, REQUIRED — this leg's own ticket number under the booking's reference (`-`), issued once and never re-used - direction: string (arrival, departure), REQUIRED - service_type: string (shared, private), REQUIRED - from: string or null, REQUIRED - to: string or null, REQUIRED - airport_code: string or null, REQUIRED - resort: string or null, REQUIRED - pickup_address: string or null, REQUIRED - dropoff_address: string or null, REQUIRED - flight_no: string or null, REQUIRED - flight_time: string, date-time or null, REQUIRED - pickup_time: string, date-time, REQUIRED - follow_flight_delays: boolean, REQUIRED — 1.19.0: true when a late flight moves this pickup; false when the passenger keeps their own pickup (a delay is recorded and the pickup stays, unless the plane lands after it: then it becomes the landing and Winteride calls the passenger) - pax: integer, REQUIRED - luggage: integer, REQUIRED - ski: integer, REQUIRED - trolley: integer, REQUIRED - vehicle_class: string or null, REQUIRED - notices: array of Notice — 1.20.0: only on a shared leg: what a shared seat is (see `Notice`). Show it where you show the leg's pickup time: that time can change until the day before the trip, and the passenger's email is told the new one. Absent on a private leg. - code: string, REQUIRED — stable; the kind of notice - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - arrival_pickup: ArrivalPickup — 1.21.0: only on an ARRIVAL leg whose landing Winteride knows (a time you or your client gave, the flight list's, or the flight feed's): when we expect to meet the passenger. The leg's `pickup_time` stays the landing; this says the landing, the minutes it takes to leave the airport (passport control and baggage) and the expected pickup, each as its own field, and the words to show your client. Absent on every other leg. - basis: string (landing, stated, shared_van), REQUIRED — `landing`: a pickup derived from the flight (the landing plus the minutes); `stated`: a pickup that was chosen (shown as it is, nothing recalculated); `shared_van`: a shared seat, whose van leaves after the flights it waits for - landing_time: string, date-time, REQUIRED — the flight's landing, as Winteride holds it - minutes_to_leave_airport: integer or null, REQUIRED — minutes from the landing to the expected pickup; null on a stated pickup - expected_pickup_time: string, date-time, REQUIRED — when we expect to meet the passenger (a shared van: when it is expected to leave the airport) - follows_flight: boolean, REQUIRED — true when a late flight moves the pickup, and with it this time - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) - currency: string or null, REQUIRED - gross_minor: integer or null, REQUIRED — the public fare - commission_bps: integer or null, REQUIRED - net_minor: integer or null, REQUIRED — what you pay - charged_on_credit_minor: integer, REQUIRED - cancel_preview: CancelPreview - cancellable: boolean, REQUIRED - currency: string or null, REQUIRED - fee_minor: integer, REQUIRED - credit_reversal_minor: integer, REQUIRED — given back to your credit line - credit_fee_minor: integer, REQUIRED — the fee kept - refund_minor: integer, REQUIRED — what goes back to a card (No other field: an unknown one is refused 422 by name.) - group_ref: string — a booking made in a group - group_seq: integer - voucher_to: string (passenger, agent) - awaiting_confirmation: object — 1.22.0: only while a booking you made inside one of your closed stop-sale windows waits for Winteride's confirmation (its `status` is `on_request`, or `quoted` or `awaiting_approval` on those rails): the booking is received, no vehicle is placed, nothing is charged and no voucher is issued until our office confirms it. Absent on every other booking, and once the office has confirmed or declined it. - reason: string (stop_sale), REQUIRED - message: string, REQUIRED — one sentence in the language you asked for; show it to your user (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) ### POST /bookings — Create a booking operationId: createBooking. Credential: PartnerApiKey or SessionToken. **Flat wire** (no `quote_id`; a journey named by code): the journey is quoted here and sold through the one partner sale. `price_total_cents` is the price your quote showed: it is only **compared** with the net the server derives now (`409 price_changed`, nothing written) and is **never charged**. Answered `201` with `{ref, booking_id, status, price_total_cents, currency, paid_by, ...}`. **Quote-first wire** (a `quote_id` and an `option_key`): books a stored quote; the price is the quote's; answered `201` with the booking as `GET /bookings/{ref}` shows it, plus `settlement`. `settle` is how it is paid: `credit` (your credit line; the default is your account's own setting), `card` (a pending card payment; the flat answer carries `payment_id` and `payment_url`), or `approval` (held for Winteride's approval; nothing is drawn). Over the credit line the booking is refused whole, `409 credit_limit_exceeded`. **Stop sale, a booking taken on request (since 1.22.0):** while stop sale is on, a booking with a leg whose pickup falls in a window closed to your account (see `GET /stop-sale`) is still taken: `201`, `status` `on_request`, and `awaiting_confirmation` (`{reason: "stop_sale", message}`) says it waits for our confirmation. No vehicle is placed, nothing is charged (a card sale opens an authorise-only page) and no voucher is issued (`409 voucher_not_issued`) until our office confirms it; the office may also decline it, and then it is `cancelled` and nothing was charged. Read the booking again to see the outcome. **Stop sale, a booking refused (since 1.18.0, only when Winteride has switched refusals on):** a booking with a leg whose pickup falls in a window closed to your account (see `GET /stop-sale`: our free vans are at or below the reserve held back from you) is refused `409 stop_sale`, nothing held, nothing charged. `context.legs` names each refused leg: its `sequence_no`, the closed `window` (`from` and `until` on the place's clock with its `zone`, and the same instants in UTC, `from_utc` and `until_utc`; `open_started` and `open_ended` are true when the closure may begin earlier or end later than shown), the `free_vans` and the `reserve`, and `messages`, the sentence in English, Hebrew and French (`message` is in the language you asked for). `override_possible` is `false` here: only Winteride's office can book through a closed window. A quote is never refused. Contact the office, or sell outside the window. **Retrying:** send your own key — `client_ref` in the body, else the `Idempotency-Key` header (the body wins; at most 80 characters). A repeat is answered `200` with the booking you already have (`duplicate: true`), before anything is quoted for a key you used before and before the price is compared; nothing is created, held or charged. The same traveller on the same trip is a repeat too (`matched_on: fingerprint`), and so is a stored quote you re-send (`quote_id`). `force` is the office's: refused `422 force_is_the_offices`. Parameters: - Idempotency-Key (in header): string — The same as the body's `client_ref` (at most 80 characters), read only when the body sends none. Body fields: One of — FlatBookingRequest: (FlatBookingRequest) A time is required: `flight_no`, `flight_time` or `pickup_time` (a shared seat needs `flight_no` or `flight_time`). A body naming the partner, the channel or a price (`agent_id`, `source`, `price`, `net_minor`, `commission_bps`, ...) is refused by name. - service_type: string (shared, private), REQUIRED - trip_type: string (one_way, round_trip) [default "one_way"] - airport_code: string, REQUIRED - resort_slug: string, REQUIRED - date: string, date, REQUIRED - pax: integer, REQUIRED [min 1] - luggage: integer [min 0; default 0] - trolley: integer [min 0; default 0] - ski: integer [min 0; default 0] - flight_no: string - flight_time: string, date-time - direction: string (arrival, departure) [default "arrival"] - out_direction: string (arrival, departure) — the same as `direction` - pickup_time: string, date-time - price_total_cents: integer, REQUIRED [min 0] — The net your quote showed. Only COMPARED with the server's net now: a difference is `409 price_changed` and nothing is written; it is never charged. - currency: string — must be the route's currency - chosen_class: string — a private seat's vehicle class, by name or id (any case); the cheapest that fits when omitted; ignored for shared - settle: string (credit, card, approval) — the default is your account's own setting - client_ref: string [min length 1; max length 80] — your key for this booking; a repeat of it is answered 200 - dropoff_address: string - dropoff_share_later: boolean - customer: object, REQUIRED — The traveller: a name, a phone with its country code and an email, all three required (since 2026-11-05 every booking names both an email and a phone). A missing or malformed one is `422` naming `customer.phone` or `customer.email` (`reason` `phone_required`, `phone_invalid`, `email_required` or `email_invalid`). - name: string, REQUIRED - phone: string, REQUIRED — E.164, with the country code - email: string, email, REQUIRED (No other field: an unknown one is refused 422 by name.) - supplements: array of object - id: string - qty: integer [min 1] - return_date: string, date - return_flight_no: string - return_flight_time: string, date-time - return_pickup_time: string, date-time - return_luggage: integer [min 0] - return_ski: integer [min 0] - return_trolley: integer [min 0] — must equal `trolley` - return_service_type: string (shared, private) - return_chosen_class: string — must equal `chosen_class`: a round trip travels in one class - return_airport_code: string — must be the same airport - return_pax: integer [min 1] — must be the same party (No other field: an unknown one is refused 422 by name.) One of — QuoteFirstBookingRequest: (QuoteFirstBookingRequest) The price is the stored quote's: this body does not take `price_total_cents`. - quote_id: string, REQUIRED - option_key: string, REQUIRED - contact: object, REQUIRED — The traveller, `{name, phone, email}`, all three required (since 2026-11-05 every booking names both an email and a phone). A missing or malformed one is `422` naming `contact.phone` or `contact.email` (`reason` `phone_required`, `phone_invalid`, `email_required` or `email_invalid`). - name: string, REQUIRED - phone: string, REQUIRED — E.164, with the country code - email: string, email, REQUIRED - flight_no: string - flight_time: string, date-time - dropoff_address: string - pickup_address: string - settle: string (credit, card, approval) - reason: string - client_ref: string [min length 1; max length 80] (No other field: an unknown one is refused 422 by name.) Example body: {"service_type": "shared", "trip_type": "one_way", "airport_code": "GVA", "resort_slug": "val-thorens", "date": "2026-12-17", "pax": 2, "luggage": 2, "trolley": 2, "ski": 2, "flight_no": "LY345", "out_direction": "arrival", "price_total_cents": 16200, "settle": "credit", "client_ref": "crm-order-48213", "customer": {"name": "Dana Levi", "phone": "+972501234567", "email": "dana@example.com"}} Answers: - 201 -> FlatBookingResult | QuoteFirstBookingResult: Booking created - 200 -> DuplicateBooking: **A repeat, not a new booking.** You already have this booking: nothing was created, held or charged. Treat it as success and keep `ref`. - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 409 -> Error: `price_changed` (the figure you sent is not the net now; `context` names both), `credit_limit_exceeded`, `capacity_exceeded`, `stop_sale` (a leg's pickup is in a window closed to your account; `context.legs` names it), or another refusal of the sale. - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (201): One of — FlatBookingResult: - ref: string, REQUIRED - booking_id: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - price_total_cents: integer, REQUIRED — what the booking costs YOU (your net) - currency: string, REQUIRED - paid_by: string (agent_credit, card, pending_approval), REQUIRED - payment_id: string or null — a card sale only - payment_url: string or null — a card sale only: the hosted page your client pays on - awaiting_confirmation: object — 1.22.0: only while a booking you made inside one of your closed stop-sale windows waits for Winteride's confirmation (its `status` is `on_request`, or `quoted` or `awaiting_approval` on those rails): the booking is received, no vehicle is placed, nothing is charged and no voucher is issued until our office confirms it. Absent on every other booking, and once the office has confirmed or declined it. - reason: string (stop_sale), REQUIRED - message: string, REQUIRED — one sentence in the language you asked for; show it to your user (No other field: an unknown one is refused 422 by name.) - tunnel_warning: object or null, REQUIRED — Advisory, present when the route crosses a closed tunnel that day; the booking is made either way. - tunnel: string - label: string - from: string - until: string - coach_driver_check: object or null, REQUIRED — Advisory driving-hours verdict for a coach or minibus; the booking is made either way. (No other field: an unknown one is refused 422 by name.) One of — QuoteFirstBookingResult: (QuoteFirstBookingResult) The booking as `GET /bookings/{ref}` shows it, plus what its rail did and the advisory checks. - id: string, REQUIRED - ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - source: string, REQUIRED - trip_type: string (one_way, round_trip, multi_leg), REQUIRED — multi_leg: a trip of more legs than a way out and a way home (a leg added to the booking, or a price offer of several legs) - tz: string — the zone this booking's pickup is read in: what the driver and the voucher show - partner_settle: string (credit, card, approval, None) or null, REQUIRED - created_at: string, date-time, REQUIRED - contact: object, REQUIRED - name: string or null, REQUIRED - email: string or null, REQUIRED - phone: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - legs: array of BookingLeg, REQUIRED - id: string, REQUIRED — the `leg_id` an amendment names - sequence_no: integer, REQUIRED - ticket_no: string or null, REQUIRED — this leg's own ticket number under the booking's reference (`-`), issued once and never re-used - direction: string (arrival, departure), REQUIRED - service_type: string (shared, private), REQUIRED - from: string or null, REQUIRED - to: string or null, REQUIRED - airport_code: string or null, REQUIRED - resort: string or null, REQUIRED - pickup_address: string or null, REQUIRED - dropoff_address: string or null, REQUIRED - flight_no: string or null, REQUIRED - flight_time: string, date-time or null, REQUIRED - pickup_time: string, date-time, REQUIRED - follow_flight_delays: boolean, REQUIRED — 1.19.0: true when a late flight moves this pickup; false when the passenger keeps their own pickup (a delay is recorded and the pickup stays, unless the plane lands after it: then it becomes the landing and Winteride calls the passenger) - pax: integer, REQUIRED - luggage: integer, REQUIRED - ski: integer, REQUIRED - trolley: integer, REQUIRED - vehicle_class: string or null, REQUIRED - notices: array of Notice — 1.20.0: only on a shared leg: what a shared seat is (see `Notice`). Show it where you show the leg's pickup time: that time can change until the day before the trip, and the passenger's email is told the new one. Absent on a private leg. - code: string, REQUIRED — stable; the kind of notice - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - arrival_pickup: ArrivalPickup — 1.21.0: only on an ARRIVAL leg whose landing Winteride knows (a time you or your client gave, the flight list's, or the flight feed's): when we expect to meet the passenger. The leg's `pickup_time` stays the landing; this says the landing, the minutes it takes to leave the airport (passport control and baggage) and the expected pickup, each as its own field, and the words to show your client. Absent on every other leg. - basis: string (landing, stated, shared_van), REQUIRED — `landing`: a pickup derived from the flight (the landing plus the minutes); `stated`: a pickup that was chosen (shown as it is, nothing recalculated); `shared_van`: a shared seat, whose van leaves after the flights it waits for - landing_time: string, date-time, REQUIRED — the flight's landing, as Winteride holds it - minutes_to_leave_airport: integer or null, REQUIRED — minutes from the landing to the expected pickup; null on a stated pickup - expected_pickup_time: string, date-time, REQUIRED — when we expect to meet the passenger (a shared van: when it is expected to leave the airport) - follows_flight: boolean, REQUIRED — true when a late flight moves the pickup, and with it this time - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) - currency: string or null, REQUIRED - gross_minor: integer or null, REQUIRED — the public fare - commission_bps: integer or null, REQUIRED - net_minor: integer or null, REQUIRED — what you pay - charged_on_credit_minor: integer, REQUIRED - cancel_preview: CancelPreview - cancellable: boolean, REQUIRED - currency: string or null, REQUIRED - fee_minor: integer, REQUIRED - credit_reversal_minor: integer, REQUIRED — given back to your credit line - credit_fee_minor: integer, REQUIRED — the fee kept - refund_minor: integer, REQUIRED — what goes back to a card (No other field: an unknown one is refused 422 by name.) - group_ref: string — a booking made in a group - group_seq: integer - voucher_to: string (passenger, agent) - awaiting_confirmation: object — 1.22.0: only while a booking you made inside one of your closed stop-sale windows waits for Winteride's confirmation (its `status` is `on_request`, or `quoted` or `awaiting_approval` on those rails): the booking is received, no vehicle is placed, nothing is charged and no voucher is issued until our office confirms it. Absent on every other booking, and once the office has confirmed or declined it. - reason: string (stop_sale), REQUIRED - message: string, REQUIRED — one sentence in the language you asked for; show it to your user (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) - settlement: object - debit_minor: integer — what the credit rail debited - payment: object or null — The card page, on the card rail. - tunnel_warning: object or null - coach_driver_check: object or null Answer fields (200): - id: string, REQUIRED - ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - duplicate: boolean (True), REQUIRED - matched_on: string (client_ref, fingerprint, quote_id), REQUIRED — `client_ref` - your key; `fingerprint` - the same traveller on the same trip; `quote_id` - the stored quote you re-sent was already used for this traveller's booking. - created_at: string, date-time, REQUIRED - message: string, REQUIRED (No other field: an unknown one is refused 422 by name.) ### POST /group-bookings — Book a group as named bookings (agents; off unless Winteride switches it on) operationId: createGroupBooking. Credential: PartnerApiKey or SessionToken. An agent splits a group of 2 to 20 shared seats into **named bookings** — one real booking per row, each with its own traveller, mobile, drop-off, voucher target (`voucher_to`: `passenger` or `agent`), return date and flight, and its own cancellation. The rows are linked by `group_ref` (the first row's reference) and booked in order in ONE transaction on your credit line, priced as one party on the van: six people in three rows cost the party-of-six fare. A row can cost 0. Any row that fails writes nothing and the answer names the row. A card or an approval `settle` is refused (credit only). **Who is reached (since 2026-11-06):** the group is your order, so a row needs only its traveller's name. A row with no `phone` or `email` takes your account's own mobile and email as its booking's contact (each row's `contact_via_agent` says which); a row's own, when given, is kept. Without either on the row or on your account, the row is refused `422`. **Retrying:** send a group `client_ref` (or `Idempotency-Key`); the rows carry `#1` … `#N`. Send it again and you get the existing group with HTTP 200 and `duplicate: true`; nothing is written. This door names the journey by **ids**. The path does not exist (`404`) while Winteride has the feature off; a hotel is refused (`403`). Parameters: - Idempotency-Key (in header): string Body fields: (GroupRequest) The common journey and the rows. A body naming the partner, the channel or a price is refused by name. - airport_id: string, REQUIRED - resort_id: string, REQUIRED - direction: string (arrival, departure), REQUIRED - date: string, date - flight_no: string - flight_time: string, date-time - pickup_time: string, date-time - service_type: string (shared) — shared only - luggage: integer [min 0] - ski: integer [min 0] - trolley: integer [min 0] - dropoff_address: string - voucher_to: string (passenger, agent) - rows: array of GroupRow, REQUIRED [min items 2; max items 20] - name: string, REQUIRED - phone: string — optional; E.164, with the country code. Without it, your account's mobile - email: string, email — optional; without it, your account's email - pax: integer, REQUIRED [min 1] - dropoff_address: string - voucher_to: string (passenger, agent) - luggage: integer [min 0] - ski: integer [min 0] - trolley: integer [min 0] - returning: boolean - return_date: string, date - return_flight_no: string - return_flight_time: string, date-time - return_pickup_time: string, date-time - return_airport_id: string - return_airport_code: string - return_luggage: integer [min 0] - return_ski: integer [min 0] (No other field: an unknown one is refused 422 by name.) - client_ref: string [max length 77] — the group's key; the rows carry #1 ... #N - settle: string (credit) — credit only - reason: string - return_date: string, date - return_flight_no: string - return_flight_time: string, date-time - return_pickup_time: string, date-time - return_airport_id: string — must be the same airport - return_airport_code: string — must be the same airport (No other field: an unknown one is refused 422 by name.) Answers: - 201 -> GroupResult: The group was booked: each row's reference and price - 200 -> GroupResult: The group key already made this group: the existing group, `duplicate: true` - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 403 -> Error: Signed in, but this door is not yours (`forbidden`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 409 -> Error: A refusal of the act in the booking's or the line's current state (`error` names it) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (201): - group_ref: string, REQUIRED - pax: integer, REQUIRED - currency: string, REQUIRED - total_minor: integer, REQUIRED — what your account is charged for the whole group - charged_now_minor: integer, REQUIRED - duplicate: boolean (True) — present on a repeat - matched_on: string — present on a repeat: client_ref - message: string — present on a repeat - rows: array of object, REQUIRED - row: integer, REQUIRED - id: string, REQUIRED - ref: string, REQUIRED - name: string, REQUIRED - pax: integer, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - currency: string, REQUIRED - gross_minor: integer, REQUIRED - out_gross_minor: integer, REQUIRED - return_gross_minor: integer or null, REQUIRED - price_minor: integer, REQUIRED — this row's share of the party price (it can be 0) - charged_now_minor: integer, REQUIRED - returns: object or null, REQUIRED - date: string, date - flight_no: string or null - voucher_to: string (passenger, agent), REQUIRED - voucher_held_by_agent: boolean, REQUIRED - contact_via_agent: array of string (email, phone), REQUIRED — the parts of this booking's contact that are your own (the row gave none): [] when the traveller's own are on it (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) Answer fields (200): - group_ref: string, REQUIRED - pax: integer, REQUIRED - currency: string, REQUIRED - total_minor: integer, REQUIRED — what your account is charged for the whole group - charged_now_minor: integer, REQUIRED - duplicate: boolean (True) — present on a repeat - matched_on: string — present on a repeat: client_ref - message: string — present on a repeat - rows: array of object, REQUIRED - row: integer, REQUIRED - id: string, REQUIRED - ref: string, REQUIRED - name: string, REQUIRED - pax: integer, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - currency: string, REQUIRED - gross_minor: integer, REQUIRED - out_gross_minor: integer, REQUIRED - return_gross_minor: integer or null, REQUIRED - price_minor: integer, REQUIRED — this row's share of the party price (it can be 0) - charged_now_minor: integer, REQUIRED - returns: object or null, REQUIRED - date: string, date - flight_no: string or null - voucher_to: string (passenger, agent), REQUIRED - voucher_held_by_agent: boolean, REQUIRED - contact_via_agent: array of string (email, phone), REQUIRED — the parts of this booking's contact that are your own (the row gave none): [] when the traveller's own are on it (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) ### GET /bookings/{ref} — Get a booking (status, legs, money, cancel preview) operationId: getBooking. Credential: PartnerApiKey or SessionToken. Poll this to track a booking. The path takes the booking's **reference or id**; another partner's is `404`. `gross_minor` is the public fare, `net_minor` what you pay, `charged_on_credit_minor` what your line was debited. `cancel_preview` is what cancelling now would do, recomputed on every read. Parameters: - ref (in path): string, REQUIRED — The booking's reference (`WR-2026-00001`) or its id. Answers: - 200 -> Booking: Booking detail - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) Answer fields (200): - id: string, REQUIRED - ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - source: string, REQUIRED - trip_type: string (one_way, round_trip, multi_leg), REQUIRED — multi_leg: a trip of more legs than a way out and a way home (a leg added to the booking, or a price offer of several legs) - tz: string — the zone this booking's pickup is read in: what the driver and the voucher show - partner_settle: string (credit, card, approval, None) or null, REQUIRED - created_at: string, date-time, REQUIRED - contact: object, REQUIRED - name: string or null, REQUIRED - email: string or null, REQUIRED - phone: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - legs: array of BookingLeg, REQUIRED - id: string, REQUIRED — the `leg_id` an amendment names - sequence_no: integer, REQUIRED - ticket_no: string or null, REQUIRED — this leg's own ticket number under the booking's reference (`-`), issued once and never re-used - direction: string (arrival, departure), REQUIRED - service_type: string (shared, private), REQUIRED - from: string or null, REQUIRED - to: string or null, REQUIRED - airport_code: string or null, REQUIRED - resort: string or null, REQUIRED - pickup_address: string or null, REQUIRED - dropoff_address: string or null, REQUIRED - flight_no: string or null, REQUIRED - flight_time: string, date-time or null, REQUIRED - pickup_time: string, date-time, REQUIRED - follow_flight_delays: boolean, REQUIRED — 1.19.0: true when a late flight moves this pickup; false when the passenger keeps their own pickup (a delay is recorded and the pickup stays, unless the plane lands after it: then it becomes the landing and Winteride calls the passenger) - pax: integer, REQUIRED - luggage: integer, REQUIRED - ski: integer, REQUIRED - trolley: integer, REQUIRED - vehicle_class: string or null, REQUIRED - notices: array of Notice — 1.20.0: only on a shared leg: what a shared seat is (see `Notice`). Show it where you show the leg's pickup time: that time can change until the day before the trip, and the passenger's email is told the new one. Absent on a private leg. - code: string, REQUIRED — stable; the kind of notice - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - arrival_pickup: ArrivalPickup — 1.21.0: only on an ARRIVAL leg whose landing Winteride knows (a time you or your client gave, the flight list's, or the flight feed's): when we expect to meet the passenger. The leg's `pickup_time` stays the landing; this says the landing, the minutes it takes to leave the airport (passport control and baggage) and the expected pickup, each as its own field, and the words to show your client. Absent on every other leg. - basis: string (landing, stated, shared_van), REQUIRED — `landing`: a pickup derived from the flight (the landing plus the minutes); `stated`: a pickup that was chosen (shown as it is, nothing recalculated); `shared_van`: a shared seat, whose van leaves after the flights it waits for - landing_time: string, date-time, REQUIRED — the flight's landing, as Winteride holds it - minutes_to_leave_airport: integer or null, REQUIRED — minutes from the landing to the expected pickup; null on a stated pickup - expected_pickup_time: string, date-time, REQUIRED — when we expect to meet the passenger (a shared van: when it is expected to leave the airport) - follows_flight: boolean, REQUIRED — true when a late flight moves the pickup, and with it this time - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) - currency: string or null, REQUIRED - gross_minor: integer or null, REQUIRED — the public fare - commission_bps: integer or null, REQUIRED - net_minor: integer or null, REQUIRED — what you pay - charged_on_credit_minor: integer, REQUIRED - cancel_preview: CancelPreview - cancellable: boolean, REQUIRED - currency: string or null, REQUIRED - fee_minor: integer, REQUIRED - credit_reversal_minor: integer, REQUIRED — given back to your credit line - credit_fee_minor: integer, REQUIRED — the fee kept - refund_minor: integer, REQUIRED — what goes back to a card (No other field: an unknown one is refused 422 by name.) - group_ref: string — a booking made in a group - group_seq: integer - voucher_to: string (passenger, agent) - awaiting_confirmation: object — 1.22.0: only while a booking you made inside one of your closed stop-sale windows waits for Winteride's confirmation (its `status` is `on_request`, or `quoted` or `awaiting_approval` on those rails): the booking is received, no vehicle is placed, nothing is charged and no voucher is issued until our office confirms it. Absent on every other booking, and once the office has confirmed or declined it. - reason: string (stop_sale), REQUIRED - message: string, REQUIRED — one sentence in the language you asked for; show it to your user (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) ### POST /bookings/{ref}/amend/preview — Preview the price effect of an amendment operationId: previewAmendment. Credential: PartnerApiKey or SessionToken. Name each leg by its `id` and send only what changes (`pickup_time`, `pax`, `luggage`, `ski`, `vehicle_class_id`, `trolley`, `flight_no`, `flight_time`, `dropoff_address`, `pickup_address`; a hotel's addresses are its account's). Anything else is refused by name. Nothing is changed. Parameters: - ref (in path): string, REQUIRED — The booking's reference (`WR-2026-00001`) or its id. Body fields: - legs: array of AmendLeg, REQUIRED [min items 1] - leg_id: string, REQUIRED - pickup_time: string, date-time - pax: integer [min 1] - luggage: integer [min 0] - ski: integer [min 0] - vehicle_class_id: string - trolley: integer [min 0] - flight_no: string - flight_time: string, date-time - dropoff_address: string - pickup_address: string (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) Example body: {"legs": [{"leg_id": "3a00894b-e7f7-4552-a7b9-1abc187dfcef", "pax": 3}]} Answers: - 200 -> AmendPreview: The price and settlement effect - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (200): (AmendPreview) The price and settlement effect; further detail fields may appear. - booking_id: string, REQUIRED - ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - status_after: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - currency: string, REQUIRED - can_confirm: boolean, REQUIRED — false: `settlement.partner_refusal` says why - capacity_ok: boolean, REQUIRED - no_change: boolean, REQUIRED - price: object, REQUIRED - delta_minor: integer, REQUIRED — the change in the public fare - total_before_minor: integer, REQUIRED - total_after_minor: integer, REQUIRED - version_no: integer - writes_new_version: boolean - legs: array of object, REQUIRED - leg_id: string, REQUIRED - changes: object, REQUIRED - price: object, REQUIRED - settlement: object, REQUIRED - settle_method: string, REQUIRED - credit_debit_minor: integer, REQUIRED — what your line is debited (your net of the delta) - credit_refund_minor: integer, REQUIRED - partner_refusal: string or null ### POST /bookings/{ref}/amend — Amend a booking operationId: commitAmendment. Credential: PartnerApiKey or SessionToken. The same `legs` as the preview and the **delta the preview showed** (`expected_delta_minor`, the change in the public fare). Any other figure is `409 amendment_price_changed`; an omitted one is `422`. Charges or refunds the difference on the booking's rail. Parameters: - ref (in path): string, REQUIRED — The booking's reference (`WR-2026-00001`) or its id. Body fields: - legs: array of AmendLeg, REQUIRED [min items 1] - leg_id: string, REQUIRED - pickup_time: string, date-time - pax: integer [min 1] - luggage: integer [min 0] - ski: integer [min 0] - vehicle_class_id: string - trolley: integer [min 0] - flight_no: string - flight_time: string, date-time - dropoff_address: string - pickup_address: string (No other field: an unknown one is refused 422 by name.) - expected_delta_minor: integer, REQUIRED — the `price.delta_minor` the preview showed (No other field: an unknown one is refused 422 by name.) Answers: - 200 -> AmendResult: Amended - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 409 -> Error: A refusal of the act in the booking's or the line's current state (`error` names it) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (200): - booking_id: string, REQUIRED - ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - legs: array of object, REQUIRED - leg_id: string, REQUIRED - changes: object, REQUIRED - price: object, REQUIRED - delta_minor: integer, REQUIRED - total_minor: integer, REQUIRED - version_no: integer - wrote_new_version: boolean - settlement: object, REQUIRED - settle_method: string, REQUIRED - credit_debit_minor: integer, REQUIRED ### POST /bookings/{ref}/cancel — Cancel a booking operationId: cancelBooking. Credential: PartnerApiKey or SessionToken. The body may carry a `reason` (text) and nothing else; the office's own options (a fee override, a no-show) are refused by name. The answer is the cancelled booking plus `cancellation`: `credit_reversal_minor` is given back to your credit line, `credit_fee_minor` is the fee kept, `refund_minor` is what goes back to a card. What a cancellation costs depends on how long before the leg's flight it is made, on the partner ladder in your agreement; read it from `cancel_preview` on your own booking rather than hard-coding it. Parameters: - ref (in path): string, REQUIRED — The booking's reference (`WR-2026-00001`) or its id. Body fields: - reason: string — free text, at most 300 characters are kept (No other field: an unknown one is refused 422 by name.) Answers: - 200 -> CancelResult: Cancelled - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 409 -> Error: A refusal of the act in the booking's or the line's current state (`error` names it) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (200): (CancelResult) The cancelled booking (as `GET /bookings/{ref}` shows it, without `cancel_preview`) plus what the cancellation did. - id: string, REQUIRED - ref: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - source: string, REQUIRED - trip_type: string (one_way, round_trip, multi_leg), REQUIRED — multi_leg: a trip of more legs than a way out and a way home (a leg added to the booking, or a price offer of several legs) - tz: string — the zone this booking's pickup is read in: what the driver and the voucher show - partner_settle: string (credit, card, approval, None) or null, REQUIRED - created_at: string, date-time, REQUIRED - contact: object, REQUIRED - name: string or null, REQUIRED - email: string or null, REQUIRED - phone: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - legs: array of BookingLeg, REQUIRED - id: string, REQUIRED — the `leg_id` an amendment names - sequence_no: integer, REQUIRED - ticket_no: string or null, REQUIRED — this leg's own ticket number under the booking's reference (`-`), issued once and never re-used - direction: string (arrival, departure), REQUIRED - service_type: string (shared, private), REQUIRED - from: string or null, REQUIRED - to: string or null, REQUIRED - airport_code: string or null, REQUIRED - resort: string or null, REQUIRED - pickup_address: string or null, REQUIRED - dropoff_address: string or null, REQUIRED - flight_no: string or null, REQUIRED - flight_time: string, date-time or null, REQUIRED - pickup_time: string, date-time, REQUIRED - follow_flight_delays: boolean, REQUIRED — 1.19.0: true when a late flight moves this pickup; false when the passenger keeps their own pickup (a delay is recorded and the pickup stays, unless the plane lands after it: then it becomes the landing and Winteride calls the passenger) - pax: integer, REQUIRED - luggage: integer, REQUIRED - ski: integer, REQUIRED - trolley: integer, REQUIRED - vehicle_class: string or null, REQUIRED - notices: array of Notice — 1.20.0: only on a shared leg: what a shared seat is (see `Notice`). Show it where you show the leg's pickup time: that time can change until the day before the trip, and the passenger's email is told the new one. Absent on a private leg. - code: string, REQUIRED — stable; the kind of notice - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - arrival_pickup: ArrivalPickup — 1.21.0: only on an ARRIVAL leg whose landing Winteride knows (a time you or your client gave, the flight list's, or the flight feed's): when we expect to meet the passenger. The leg's `pickup_time` stays the landing; this says the landing, the minutes it takes to leave the airport (passport control and baggage) and the expected pickup, each as its own field, and the words to show your client. Absent on every other leg. - basis: string (landing, stated, shared_van), REQUIRED — `landing`: a pickup derived from the flight (the landing plus the minutes); `stated`: a pickup that was chosen (shown as it is, nothing recalculated); `shared_van`: a shared seat, whose van leaves after the flights it waits for - landing_time: string, date-time, REQUIRED — the flight's landing, as Winteride holds it - minutes_to_leave_airport: integer or null, REQUIRED — minutes from the landing to the expected pickup; null on a stated pickup - expected_pickup_time: string, date-time, REQUIRED — when we expect to meet the passenger (a shared van: when it is expected to leave the airport) - follows_flight: boolean, REQUIRED — true when a late flight moves the pickup, and with it this time - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) - currency: string or null, REQUIRED - gross_minor: integer or null, REQUIRED — the public fare - commission_bps: integer or null, REQUIRED - net_minor: integer or null, REQUIRED — what you pay - charged_on_credit_minor: integer, REQUIRED - cancel_preview: CancelPreview - cancellable: boolean, REQUIRED - currency: string or null, REQUIRED - fee_minor: integer, REQUIRED - credit_reversal_minor: integer, REQUIRED — given back to your credit line - credit_fee_minor: integer, REQUIRED — the fee kept - refund_minor: integer, REQUIRED — what goes back to a card (No other field: an unknown one is refused 422 by name.) - group_ref: string — a booking made in a group - group_seq: integer - voucher_to: string (passenger, agent) - awaiting_confirmation: object — 1.22.0: only while a booking you made inside one of your closed stop-sale windows waits for Winteride's confirmation (its `status` is `on_request`, or `quoted` or `awaiting_approval` on those rails): the booking is received, no vehicle is placed, nothing is charged and no voucher is issued until our office confirms it. Absent on every other booking, and once the office has confirmed or declined it. - reason: string (stop_sale), REQUIRED - message: string, REQUIRED — one sentence in the language you asked for; show it to your user (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) - cancellation: object, REQUIRED - refund_minor: integer, REQUIRED - credit_reversal_minor: integer, REQUIRED - credit_fee_minor: integer, REQUIRED (No other field: an unknown one is refused 422 by name.) ### GET /bookings/{ref}/voucher — Get the customer voucher for a booking operationId: getVoucher. Credential: PartnerApiKey or SessionToken. The customer-facing voucher: legs, pickup times, the driver once assigned, addresses. A booking held for approval, or cancelled, has none: `409 voucher_not_issued`. On confirmation the voucher is sent to you by email and WhatsApp, on the contacts on your partner profile, in your chosen language; your traveller's own copy follows only once the first leg is within the platform's quiet window (`agent_client_quiet_hours`, 48 hours by default), and never for a booking whose voucher you hold (`voucher_to: agent`). **Planned / not yet available:** a public shareable `voucher_url`. Parameters: - ref (in path): string, REQUIRED — The booking's reference (`WR-2026-00001`) or its id. Answers: - 200 -> Voucher: Voucher - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 409 -> Error: A refusal of the act in the booking's or the line's current state (`error` names it) Answer fields (200): - id: string, REQUIRED - ref: string, REQUIRED - ref_full: string, REQUIRED - status: BookingStatus, REQUIRED — `quoted` while a card payment is pending; `on_request` while Winteride is still to arrange the vehicle or the van is still to fill; `confirmed`; then `completed`. `awaiting_approval` when held for Winteride's approval; `cancelled` is terminal. (`draft` is a booking the office is still composing; a partner never sees one.) The driver, once assigned, is on the voucher, not a status. - trip_type: string (one_way, round_trip, multi_leg), REQUIRED - tz: string or null, REQUIRED - total_minor: integer or null, REQUIRED — the retail total the traveller sees - currency: string or null, REQUIRED - contact: object, REQUIRED - name: string or null, REQUIRED - email: string or null, REQUIRED - phone: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - is_last_minute: boolean, REQUIRED - display: object or null — an indicative second currency, only when it applies - legs: array of object, REQUIRED - sequence_no: integer, REQUIRED - ticket_no: string or null, REQUIRED — this leg's own ticket number under the booking's reference - direction: string (arrival, departure), REQUIRED - service_type: string (shared, private), REQUIRED - from: string or null, REQUIRED - to: string or null, REQUIRED - airport_code: string or null, REQUIRED - airport_name: string or null, REQUIRED - resort: string or null, REQUIRED - pickup_address: string or null, REQUIRED - pickup_address_pending: boolean, REQUIRED — 1.17.0: a departure booked with its pickup address to follow; true until one is written (the voucher then says 'Address to follow') - dropoff_address: string or null, REQUIRED - flight_no: string or null, REQUIRED - flight_time: string, date-time or null, REQUIRED - pickup_time: string, date-time, REQUIRED - pickup_time_final: boolean, REQUIRED - follow_flight_delays: boolean, REQUIRED — 1.19.0: true when a late flight moves this pickup; false when the passenger keeps their own pickup - pax: integer, REQUIRED - luggage: integer, REQUIRED - ski: integer, REQUIRED - trolley: integer, REQUIRED - vehicle: string or null, REQUIRED - driver: object or null, REQUIRED - name: string - phone: string or null - depart_est: string, date-time or null, REQUIRED - supplements: array of object, REQUIRED - notices: array of Notice — 1.20.0: only on a shared leg: what a shared seat is (see `Notice`), in your language. Absent on a private leg. - code: string, REQUIRED — stable; the kind of notice - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) - arrival_pickup: ArrivalPickup — 1.21.0: only on an ARRIVAL leg whose landing Winteride knows (a time you or your client gave, the flight list's, or the flight feed's): when we expect to meet the passenger. The leg's `pickup_time` stays the landing; this says the landing, the minutes it takes to leave the airport (passport control and baggage) and the expected pickup, each as its own field, and the words to show your client. Absent on every other leg. - basis: string (landing, stated, shared_van), REQUIRED — `landing`: a pickup derived from the flight (the landing plus the minutes); `stated`: a pickup that was chosen (shown as it is, nothing recalculated); `shared_van`: a shared seat, whose van leaves after the flights it waits for - landing_time: string, date-time, REQUIRED — the flight's landing, as Winteride holds it - minutes_to_leave_airport: integer or null, REQUIRED — minutes from the landing to the expected pickup; null on a stated pickup - expected_pickup_time: string, date-time, REQUIRED — when we expect to meet the passenger (a shared van: when it is expected to leave the airport) - follows_flight: boolean, REQUIRED — true when a late flight moves the pickup, and with it this time - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) - tickets: array of VoucherTicket, REQUIRED — 1.17.0: one ticket per ride, in travel order, its words in your language: what the traveller's voucher draws - sequence_no: integer, REQUIRED - ticket_no: string or null, REQUIRED - kind: string (shared, private), REQUIRED - kind_words: string, REQUIRED - direction: string (arrival, departure), REQUIRED - ride_no: integer, REQUIRED — its place among the booking's live rides, from 1 - day: string, date or null, REQUIRED — the pickup's day on the booking's clock (`tz`) - band: string, REQUIRED — the ride's heading, e.g. 'Arrival · Thu 17 Dec' - from: string or null, REQUIRED - to: string or null, REQUIRED - flight_no: string or null, REQUIRED - flight_time: string, date-time or null, REQUIRED - pickup_at: string, date-time or null, REQUIRED — the van's estimated departure on a shared ride that has one, else the pickup - pickup_time_final: boolean, REQUIRED - van_leaves: boolean, REQUIRED — true when `pickup_at` is a shared van's estimated departure - pickup_place: string or null, REQUIRED — where to meet: the arrivals hall, the address, or 'Address to follow' - pickup_address_pending: boolean, REQUIRED - dropoff_address: string or null, REQUIRED - pax: integer, REQUIRED - luggage: integer, REQUIRED - ski: integer, REQUIRED - party: string, REQUIRED - driver: object or null, REQUIRED - name: string, REQUIRED - phone: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - vehicle: string or null, REQUIRED - extras: array of string, REQUIRED - facts: array of object, REQUIRED — the three facts side by side: an arrival's flight, pickup, driver; a departure's pickup, flight, driver - key: string (flight, pickup, driver), REQUIRED - label: string, REQUIRED - value: string or null, REQUIRED - sub: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - details: array of object, REQUIRED - key: string (dropoff, party, extras), REQUIRED - label: string, REQUIRED - value: string or null, REQUIRED (No other field: an unknown one is refused 422 by name.) - meeting: object or null — 1.21.0: on an arrival whose landing is known, when we expect to meet the passenger, in words (the leg's `arrival_pickup`); null otherwise - title: string, REQUIRED - text: string, REQUIRED (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) ### GET /stop-sale — When not to sell (off unless Winteride switches it on) operationId: getStopSale. Credential: PartnerApiKey or SessionToken. The windows in which our own free vans are down to the reserve held back from **your** account, for a range of at most 62 days (today and the platform's horizon by default). A booking with a pickup in one of these windows is taken on request (since 1.22.0: `awaiting_confirmation` on the booking), or refused (`409 stop_sale`, since 1.18.0) once Winteride has switched refusals on; a window can close after you read it. Thirty a minute per address. The path does not exist (`404`) while Winteride has the feature off. Parameters: - from (in query): string, date - to (in query): string, date Answers: - 200 -> StopSale: Your own picture - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values - 429 -> Error: Too many calls for your key, or from one address on the doors that say so (`rate_limited`); retry after the `Retry-After` header Answer fields (200): - from: string, date, REQUIRED - to: string, date, REQUIRED - reserve: integer, REQUIRED — how many vehicles are held back from your account before a window closes - windows: array of object, REQUIRED - service_date: string, date, REQUIRED - starts_at: string, date-time, REQUIRED - ends_at: string, date-time, REQUIRED - free_vans: integer, REQUIRED — left at the tightest moment of the window (0: the fleet was full) (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) ### POST /mcp — The partner MCP connector (one JSON-RPC message per POST; off unless Winteride switches it on) operationId: partnerMcp. Credential: PartnerApiKey. The Model Context Protocol over Streamable HTTP, for an AI agent acting as your account: revision `2026-07-28` (every request carries `params._meta["io.modelcontextprotocol/protocolVersion"]` and `clientCapabilities`, mirrored in the `MCP-Protocol-Version`, `Mcp-Method` and, for `tools/call`, `Mcp-Name` headers; `server/discover` lists the versions) and the earlier `2025-11-25`, `2025-06-18` and `2025-03-26` (an `initialize` handshake; no session is minted). The tools are `search_routes_and_resorts`, `get_quote`, `create_booking` (it requires an `idempotency_key`), `list_bookings`, `get_booking`, `preview_amendment`, `amend_booking`, `cancel_booking`, `lookup_flight` and `get_voucher`; each runs the door of this API it names, with the same prices and rules, and a door's refusal is the tool's error result carrying this API's error envelope and status. Your **API key** alone (`PartnerApiKey`): a session token is `401`. A request from a browser (an `Origin` header) is `403`. Sixty calls a minute per key, beside the API's own limit per key. A batch is refused (one message per POST); a notification is `202`. `GET` and `DELETE` answer `405`. The path does not exist (`404`) while Winteride has the connector off. Parameters: - MCP-Protocol-Version (in header): string - Mcp-Method (in header): string - Mcp-Name (in header): string Body fields: (JsonRpcRequest) One JSON-RPC 2.0 request (with an `id`) or notification (without one). `params._meta` carries the protocol version and the client's capabilities in the current revision; `tools/call` names the tool in `params.name` and its arguments in `params.arguments`. - jsonrpc: string (2.0), REQUIRED - id: string | integer - method: string, REQUIRED - params: object Example body: {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {}}}} Answers: - 200 -> JsonRpcResponse: The JSON-RPC reply (a `result`, or an `error` the message itself caused) - 202: A notification was accepted; there is no body - 400 -> JsonRpcResponse: A malformed message (`-32600`, `-32700`, `-32602`), a header that does not match the body (`-32020`), or a protocol version this server does not speak (`-32022`, with the versions it does) - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 403 -> JsonRpcResponse | Error: A browser's `Origin`, or a partner kind the connector does not serve (an affiliate) - 404 -> JsonRpcResponse | Error: The connector is switched off (`not_found`), or a method the current revision does not have (`-32601`) - 429 -> Error: Too many calls for your key, or from one address on the doors that say so (`rate_limited`); retry after the `Retry-After` header Answer fields (200): (JsonRpcResponse) A JSON-RPC 2.0 reply. A tool's own refusal is a `result` with `isError` true, never an `error`. - jsonrpc: string (2.0), REQUIRED - id: string or null | integer — the request's id; null when it could not be read - result: object - error: object - code: integer, REQUIRED - message: string, REQUIRED - data: object ### GET /sheet/columns — The sheet's columns, served operationId: sheetColumns. Credential: SheetKeyAuth. The header a booking sheet writes, so the sheet can never drift from what Winteride reads. `columns` are the columns the agent fills (in order); `results` are the three the sheet's script writes back (`status`, `price`, `ref`). An agent's sheet has no `agent` column (a sheet books on its own account). Answers: - 200 -> SheetColumns: Columns - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 404 -> Error: Not found, not yours, or a door that is switched off (`not_found`) Answer fields (200): - columns: array of SheetColumn, REQUIRED - key: string, REQUIRED - label: string, REQUIRED - help: string, REQUIRED - results: array of SheetColumn, REQUIRED - key: string, REQUIRED - label: string, REQUIRED - help: string, REQUIRED ### POST /sheet/check — A verdict for each row; writes nothing operationId: sheetCheck. Credential: SheetKeyAuth. Quotes each row and answers what it is: the route, the product, the flight (and whether the time is `live`, from the `timetable` or `typed`), whether a seat is available or it goes on request, the seats left on that van, the price this account would pay (a return row is one price for the trip, return included), or what the row still needs. A row is read strictly: an unknown direction, service, date, time or number is a gap, never a guess. Nothing is booked, quoted or stored. At most the number of rows the system administrator allows per call (100 by default; 422 above). Body fields: - rows: array of SheetRow, REQUIRED - row_key: string, REQUIRED [max length 40] - direction: string — arrival | departure (required, no default) - airport: string - destination: string - date: string — YYYY-MM-DD or DD/MM/YYYY (day first) - flight_no: string - flight_time: string — HH:MM on the airport's clock, when there is no flight number - pax: string - luggage: string - ski: string - first_name: string - last_name: string - phone: string — the traveller's mobile, with the country code (required) - hotel: string - trip: string — 1 one way, 2 return; blank is one way unless a return date or flight is filled - return_date: string - return_flight: string - service: string — shared | private (required, no default) - email: string — the traveller's e-mail (required since 2026-11-05: every booking names both an e-mail and a mobile) (No other field: an unknown one is refused 422 by name.) (No other field: an unknown one is refused 422 by name.) Answers: - 200 -> SheetCheckResponse: One verdict per row, in order - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values - 429 -> Error: Too many calls for this key Answer fields (200): - rows: array of SheetVerdict, REQUIRED - row_key: string or null, REQUIRED - ok: boolean, REQUIRED - status: string, REQUIRED - missing: array of string — what the row still needs - route: string - product: string (shared, private) - trip_type: string (one_way, round_trip) - flight: object - flight_no: string or null - time: string or null — HH:MM on the airport's clock - source: string (live, timetable, typed) or null - on_request: boolean - price_minor: integer — what this account pays, integer minor units - currency: string - seats_remaining: integer or null - seats_total: integer or null - billed_to: string (agent, direct) - conflict: string (one_way_with_return) - reason: string - checked: integer, REQUIRED ### POST /sheet/import — Book the rows that pass operationId: sheetImport. Credential: SheetKeyAuth. Books each finished row on your credit line, in the order sent. A row is remembered by `(source, row_key)` and a hash of what it said: sending it again books nothing; an edited row that was **not** booked is sent again; a **booked** row is locked for good - never booked again, even if edited or if its booking was cancelled (the answer names the stored route and date and the booking reference). A failed row is stored with its reason. A row that says one way beside a return is refused (a contradiction). A row never overrides your credit limit, a row whose pickup has passed fails with its reason, and a card or approval `settle` is refused. Body fields: - source: string, REQUIRED [max length 200] — the spreadsheet's id - rows: array of SheetRow, REQUIRED - row_key: string, REQUIRED [max length 40] - direction: string — arrival | departure (required, no default) - airport: string - destination: string - date: string — YYYY-MM-DD or DD/MM/YYYY (day first) - flight_no: string - flight_time: string — HH:MM on the airport's clock, when there is no flight number - pax: string - luggage: string - ski: string - first_name: string - last_name: string - phone: string — the traveller's mobile, with the country code (required) - hotel: string - trip: string — 1 one way, 2 return; blank is one way unless a return date or flight is filled - return_date: string - return_flight: string - service: string — shared | private (required, no default) - email: string — the traveller's e-mail (required since 2026-11-05: every booking names both an e-mail and a mobile) (No other field: an unknown one is refused 422 by name.) - settle: string (credit) — credit only; a card or approval settle is refused (No other field: an unknown one is refused 422 by name.) Answers: - 200 -> SheetImportResponse: One answer per row, with the counts - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) - 422 -> Error: The request is wrong (`validation_error`); `context` names the field and often the allowed values Answer fields (200): - rows: array of SheetImportAnswer, REQUIRED - row_key: string or null, REQUIRED - ok: boolean, REQUIRED - status: string, REQUIRED - booking_ref: string - booking_status: string — on a locked line: the booking's status now (a cancelled booking stays locked) - locked: boolean - skipped: boolean — nothing new was booked for this ok row - matched: boolean — the account already had this booking (the duplicate guard answered) - manage_url: string - price_minor: integer or null - currency: string or null - on_request: boolean - route: string or null - date: string or null - missing: array of string - booked: integer, REQUIRED - failed: integer, REQUIRED — every row that is not ok, a gap included - skipped: integer, REQUIRED ### GET /sheet/history — What each of your lines became operationId: sheetHistory. Credential: SheetKeyAuth. Your own lines, newest first (`source` filters one spreadsheet; `limit` at most 500). Another account's lines are never shown. Parameters: - source (in query): string - limit (in query): integer Answers: - 200 -> SheetHistory: Lines - 401 -> Error: Missing, expired or wrong credential (`authentication_required`) Answer fields (200): - rows: array of object, REQUIRED - row_key: string - source: string - status: string (booked, failed) - booking_ref: string or null - error: string or null - route: string or null - date: string or null - billed_to: string (agent, direct) - created_at: string, date-time - updated_at: string, date-time ## Credentials (from the contract) - PartnerApiKey (bearer, wrp_… (an API key)): Your organisation's **API key**, sent as a bearer token by your own server. It acts only as your agency or hotel, on these doors alone; it is shown once when it is made, does not expire, and stops at once when it is rotated or revoked (from your partner portal's organisation settings, or by Winteride on request). Limited per key (`429`, `Retry-After`). - SessionToken (bearer, session token): The token a signed-in partner session answers (a code e-mailed to your login address: `POST /api/auth/code/request`, then `/api/auth/code/verify`, `portal: partner`), sent as a bearer token; for trying the API by hand. It expires (`expires_at`); sign in again. Your server uses `PartnerApiKey`. - SheetKeyAuth (bearer, wrs_p_… (48 hex)): A **sheet key**, created by the agent from its own signed-in portal (`POST /api/partner/sheet-keys`; the key is shown once, expires - at most the days Winteride allows, 90 by default - and is revoked from the portal or by Winteride). It opens the four `/sheet/...` paths and nothing else; it is not your session token and no password is ever typed into a sheet. ## The error envelope (from the contract) - error: string, REQUIRED - message: string, REQUIRED — For a person to read, in `language`: English unless the request's `Accept-Language` asks for `he` or `fr`. Branch on `error`, never on this. - language: string (en, he, fr), REQUIRED — The language `message` is in (also the `Content-Language` header). - detail: string — Only when a Hebrew or French `message` is the code's general sentence: the precise English one. - context: object — What is worth naming (the field, the allowed values, the figures). Its keys depend on the error.