Winteride Partner API — Getting Started #
Book airport ⇄ ski-resort transfers from your own system. This guide walks a travel agency / hotel / reseller through a full integration. The formal contract is openapi.yaml — import it into Postman, Insomnia, or your code generator. Version 1.22.0. Feeding an AI agent? llms.txt is this whole API in one plain-text file, and the MCP connector (§10) lets an agent use it.
This guide, the contract and llms.txt are published at https://docs.winteride.com/partner-api/: send your developers that address.
This guide cannot drift from the API. A test parses every JSON example below and checks it against what the running API really sends and accepts: the keys, the types and the status codes. If you find a difference, the guide is the bug — write to partners@winteride.com.
Status: BETA. The happy path is live and safe to integrate against: API keys, reference, flights/lookup, quotes, quote-requests, offer read/accept, booking on credit (or card, or held for approval), read by reference, amend (preview + commit), cancel, voucher, safe retries. Four optional features exist only when Winteride switches them on for the platform — group bookings, stop sale, the Google-Sheet channel (§6, §7) and the MCP connector for AI agents (§10). Anything in a "Planned / not yet available" callout — webhooks, a sandbox — is not implemented yet. Do not build against it.
1. Base URL & access #
https://winteride.com/api/partner/v1
This is the address partners have always called, and it still answers. The partners' portal answers the same API on its own name, https://partners.winteride.com/api/partner/v1: use either, with the same key. There is no separate sandbox host today (planned). Every path in this guide is relative to the base URL above.
Some doors exist only while Winteride has the feature switched on: POST /group-bookings, GET /stop-sale, the four /sheet/… paths and POST /mcp. A switched-off door answers exactly as a path that does not exist: 404 not_found. Handle that as "this feature is not enabled for the platform".
2. Authentication #
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_requiredfrom 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:
- 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/phonewith{"phone": "+…", "portal": "partner"}, then the verification with"phone"in place of"email"). At most three codes go to one address every ten minutes:
{ "email": "reservations@your-agency.example", "portal": "partner" }
- 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:
{
"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 }
}
- 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.
3. Conventions #
- 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 amountsprice_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_centssays, and it does not move when the list price does. - Booking references look like
WR-2026-00001. Price offers areWO-2026-00001until accepted. Everywhere a booking is named in a path you may use its reference or its id (§4, Step 4). - Dates are
YYYY-MM-DDand 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": "<code>", "message": "…", "language": "en", "context": { … } }(contextappears when there is something to name — the field, the allowed values). Branch onerror, never on the message.messageis for a person to read and is in English unless you ask for another language: sendAccept-Language: heorfrand it comes in Hebrew or French;language(and theContent-Languageheader) says which it is in.errorandcontextnever change with the language. When a Hebrew or Frenchmessageis the code's general sentence, the precise English one may ride along asdetail:
{ "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 everysupplementsid it could not price insupplements_ignored, and a booking that asks for one is refused422 validation_error(context.reason: supplement_not_priced,context.ignored), nothing written.
4. The booking flow #
reference ─▶ quote ─▶ book ─▶ read ─▶ voucher ─▶ (amend / cancel)
Step 0 — Your profile and language #
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" }'
{
"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.
{ "language": "fr" }
Step 1 — Load reference data (cache it) #
curl https://$HOST/api/partner/v1/reference -H "Authorization: Bearer $WINTERIDE_API_KEY"
{
"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 ids. 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:
curl -X POST https://$HOST/api/partner/v1/quotes \
-H "Authorization: Bearer $WINTERIDE_API_KEY" -H "Content-Type: application/json" -d @quote.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:
{
"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, notshared.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 readsundefined, 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.eligibleshared.availableshared.amount_centsshared.price_centsprivate[].amount_centsprivate[].price_centsprivate[].class_idprivate[].vehicle_class_idflight.noflight.flight_noshared.availability(traffic light)shared.seats_remaining(a number)shared.min_met: falseshared.on_request: true
Why shared is not offered, and what to change #
If you want a shared price, send
flight_noorflight_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, andsharedcomes backavailable: falsewithreason: "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. Apickup_timealone is not a flight.
{ "airport_code": "GVA", "resort_slug": "val-thorens", "pax": 2, "date": "2026-12-17", "direction": "arrival" }
{
"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:
{ "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:
{ "airport_id": "…", "resort_id": "…", "service_type": "private", "pax": 2,
"flight_no": "LY345", "date": "2026-12-17", "direction": "arrival" }
{
"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:
{
"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:
{
"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:
{
"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 |
{
"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_timefor a one-way resort → airport trip,return_pickup_timefor 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_finalon 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:
{
"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:
{
"quote_id": "…", "option_key": "private:…",
"contact": { "name": "Eli Bar", "phone": "+972502223344", "email": "eli@example.com" },
"settle": "credit", "client_ref": "qf-1"
}
{
"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.
{
"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 }
]
}
{
"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 <key>#1 … <key>#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 #
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.
{
"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.
{ "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 #
curl https://$HOST/api/partner/v1/bookings/WR-2026-00001/voucher -H "Authorization: Bearer $WINTERIDE_API_KEY"
{
"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_urllink.
5. Amending & cancelling #
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:
{ "legs": [ { "leg_id": "…", "pax": 3 } ] }
{
"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:
{ "legs": [ { "leg_id": "…", "pax": 3 } ], "expected_delta_minor": 7500 }
{
"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.
{ "reason": "plans changed" }
{
"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.
6. Other doors #
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.
{
"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):
{
"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:
"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):
{
"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/.
7. Safe-retry summary #
| 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) |
8. Price offers — on-request and custom routes #
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.
{ "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" } }
{ "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:
{
"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
}
{ "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).
9. Webhooks — Planned / not yet available #
There is no webhook system today — no delivery, no signing, no events. Track booking state by polling
GET /bookings/{ref}. Do not build a webhook receiver against Winteride yet.
When webhooks ship, the intended shape (subject to change) is a signed POST to a URL you register, with an X-Winteride-Signature (HMAC-SHA256) header and events like booking.confirmed, booking.completed, booking.cancelled, booking.amended. This is a preview of direction only — not a contract.
10. AI agents: llms.txt and the MCP connector #
Feeding an agent the API. 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:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list",
"params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {} } } }
{
"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.
11. Errors & status codes #
| 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. |
12. Rate limits #
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.
13. Changelog #
One series, newest first.
v1.22 — this version
- A booking in a closed stop-sale window is taken on request (
awaiting_confirmation). While stop sale is on, a booking with a leg whose pickup is in a window closed to your account (GET /stop-sale) is no longer simply let through: it is taken on request. The answer is still201; itsstatusison_request, and the booking carriesawaiting_confirmation:{ "reason": "stop_sale", "message": "..." }, the sentence in your language. 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 answer409 voucher_not_issueduntil our office confirms the booking. When the office confirms it, the booking isconfirmed, the key is gone and the voucher is issued as usual; when the office declines it, the booking iscancelledand nothing was charged.GET /bookings/{ref},GET /bookingsand both booking wires carry the key. Where Winteride has switched refusals on, the409 stop_saleof 1.18.0 answers instead. A hotel's ASAP request and a hotel's seat on a named van are not held. Additive: nothing was removed, renamed or changed; a client that already handleson_requestkeeps working. Show themessageto your user.
v1.21
- When we expect to meet a passenger who lands (
arrival_pickup). An arrival'spickup_timeis the landing: the van is planned from it, and it is what a late flight moves. A passenger is met later, after passport control and baggage. So every arrival leg whose landing we know (a time you or your client gave, the flight list's, or the flight feed's) ofGET /bookings/{ref}, ofGET /bookings, of the voucher, and every one-way arrival option of the quote-firstPOST /quotes, carriesarrival_pickup:basis(landing,statedorshared_van),landing_time,minutes_to_leave_airport(45 unless Winteride has set another; null on a pickup that was chosen), andexpected_pickup_time, each as its own field, so you never do the arithmetic;follows_flight; andtitleandtext, the words in your language: "Your flight lands at 09:15. We expect to meet you at about 10:00, after passport control and baggage. If the flight is late, the pickup follows it." A pickup that was chosen is shown as it is, with the landing beside it. A shared seat says when its van is expected to leave the airport. Each voucher ticket of such a leg says the expected time in its pickup fact and carriesmeeting({title, text}; null on any other ride). A departure, and a leg with no known landing, have noarrival_pickupkey. Additive: nothing was removed, renamed or changed. Show thetextto your client where you show the pickup.
v1.20
- What a shared seat is, in words (
notices). A shared transfer costs less and is less flexible: its pickup time can change, by a few minutes, until the day before the trip, when Winteride confirms the van's time, and the passenger is emailed the new time. So that you can tell your client,POST /quotessays it on an availablesharedseat, and every shared leg ofGET /bookings/{ref}, ofGET /bookingsand of the voucher carriesnotices: a list with one{code, title, text},codeshared_seat, the words in your language (Accept-Language; English when you send none). A private seat, a private leg and a seat that is not offered have nonoticeskey. Additive: nothing was removed, renamed or changed; a client that ignores an unknown field keeps working, and a client should ignore acodeit does not know. Show thetitleand thetextas they are.
v1.19
- Whether a pickup follows a late flight. Each leg of
GET /bookings/{ref}and of the voucher saysfollow_flight_delays:truewhen a late flight moves the pickup,falsewhen the passenger keeps their own pickup time (a delay is recorded and the pickup stays, unless the plane now lands after it; then the pickup becomes the landing and Winteride calls the passenger). A pickup you send isfalseby default; one the flight gives istrue. - A departure's pickup leaves the drive plus three and a half hours before the flight. A quote whose departure
pickup_timeis later than the road's drive that day plus 210 minutes before take-off is answered422withcontext.reasonpickup_too_close_to_flightandcontext.route_drive_minutes,context.min_buffer_minutesandcontext.latest_allowed_pickup_time(the airport's clock). With no pickup sent, the pickup given is six hours before the flight, or earlier on a long drive. Additive: a client that reads an unknown422by itsmessagekeeps working. - A shared seat to the airport follows the same lead (no field changed). With no pickup sent, a shared departure's
pickup_timeis six hours before the flight, or the drive plus 210 minutes before it when that is longer. A shared departurepickup_timeyou send that is later than that lead is refused like a private one:422withcontext.reasonpickup_too_close_to_flightand the same three figures (context.latest_allowed_pickup_timeis the lead's); an earlier one is kept. On a road with no drive figure nothing is refused. A shared van leaves for the earliest flight it carries, so the pickup of a booked shared departure can move earlier, by at most 20 minutes, when a passenger with an earlier flight joins the van; this never happens in the last 24 hours, and the voucher is sent again. Read the pickup fromGET /bookings/{ref}or the voucher, not from the quote you kept.
v1.18
- A booking in a closed stop-sale window is refused. When Winteride has switched refusals on, a booking (
POST /bookings,POST /group-bookings, the Google-Sheet channel and the MCPcreate_bookingtool) with a leg whose pickup is in a window closed to your account (GET /stop-sale) is answered409 stop_sale: nothing held, nothing charged.context.legsnames each refused leg, the closed window on the place's clock, the free vans, the reserve and the sentence in English, Hebrew and French. A quote is never refused. Additive: a client that already handles an unknown409keeps working;GET /stop-saleis unchanged. Off until Winteride switches it on.
v1.17
- The voucher's tickets.
GET /bookings/{ref}/voucheraddstickets: one per ride, in travel order, as the traveller's voucher draws it (from and to, the day, the flight, where and when to meet, the driver once named, the party), its words in your account's language. - An address to follow. Each leg of the voucher says
pickup_address_pending:trueon a departure booked with its pickup address to follow, until the address is written (the ticket then says "Address to follow" where the address would be). Your own bookings always send theirs, so yours readfalse.
v1.16
- A ticket number per leg. Every leg of a booking carries
ticket_no, its own number under the booking's reference (WR-2026-00001-1,-2), on the booking read, the booking list and the voucher. It is issued once and never re-used; existing bookings got theirs in leg order. - A group is your order. A row of
POST /group-bookingsneeds only its traveller's name: a row without aphoneor anemailis reached on your account's own, and each row of the answer says which incontact_via_agent. A row's own, when given, is still checked. A row without one when your account has none either is422naming the row. - Trips of several legs. A booking's
trip_typemay readmulti_leg(a leg your portal added, or a price offer of several legs) on the booking read, the booking list and the voucher. - High demand. A private trip quoted when every vehicle able to carry it is taken in its window carries a high-demand supplement in its net; a booking sent at an earlier quote's price is then
409 price_changed.
v1.15
- Every booking names an email and a phone. The traveller of a new booking (
customeronPOST /bookings,contacton a quote-first booking, every row ofPOST /group-bookings) needs a name, a mobile number with its country code and an email. A missing or malformed one is422naming the field, withreasonphone_required,phone_invalid,email_requiredoremail_invalid. The sheet gains an E-mail column, and a line without both is not sent. A booking made before keeps the contact it has.
v1.14
- API keys. Your server authenticates with your organisation's own key (
Authorization: Bearer wrp_…): shown once, named, rotated and revoked from your portal's organisation settings (or by Winteride on request), limited per key. A signed-in session still works for trying the API by hand. - For AI agents.
llms.txt, the whole API in one generated file, and the MCP connectorPOST /mcp(when Winteride switches it on), whose tools run these doors (§10).
v1.13
- The resort is the price zone. A booking or an amendment whose address lies more than 8 km from the resort it is priced for is refused
422 address_outside_resort_zone, naming the resort the address is in or asking for a price request (step 3). - Documentation made true to the API. The quote and the booking are documented as they run: a journey named by codes, one answer for both services (
shared.available,price_cents,seats_remaining,on_request), the reason and a hint for an unavailable shared seat, and aprice_total_centsthat is compared with the server's net (409 price_changed) and never charged. The error envelope, the booking list, amendments (by leg), cancellation, the voucher, rate limits and the offers are documented as they are. - References in paths. Every per-booking path takes the reference or the id; another partner's reference is a
404. - Group bookings.
POST /group-bookings(agents; behind a Winteride switch): named bookings priced as one party, all or nothing, retried with a group key.
v1.12
- Safe retries:
client_ref/Idempotency-Keyon booking creation; a repeat answers200withduplicate: trueand creates nothing. - Agreed shared prices. Where we have agreed a fixed shared price with you,
shared.price_centsis that price and the booking is charged it.
v1.11
- Stop sale:
GET /stop-sale, the dates and hours we cannot cover for your account. - Google-Sheet booking channel:
GET /sheet/columns,POST /sheet/check,POST /sheet/import,GET /sheet/history, with a sheet key of their own (openapi.yaml, tag Sheet;docs/integrations/google-sheets/README.md).
v1.6
- Return-leg bags now apply.
return_luggageandreturn_skichoose the return's vehicle and gate a shared seat; omitted, they fall back to the outbound.trolleyis carried on every leg and never priced.
v1.5
- Bookings accept
pickup_timeandreturn_pickup_time— the resort pickup on a departure leg, as an ISO instant. Provisional on a shared seat.
v1.1
- Quotes and bookings accept
trolley(cabin bags) alongsideluggageandski; it is carried for the driver and has no price or capacity effect. Private pricing includes luggage and ski.
Questions / account setup: partners@winteride.com. Contract of record: openapi.yaml.