Skip to content
Flyzafy DevelopersSandbox

Merchant API

Search, price, book and issue flights from your own systems.

Overview

With the Merchant API you can:

  • Shop for flights — search offers, check seat availability, take a live price, see other fare families, seat maps, paid seats and extra bags.
  • Book and issue — hold a booking and issue it later, or book and issue in one call; read it live from the airline; add seats and travel documents; cancel or void it.
  • Webhooks — receive signed events when your bookings change.

Every path in this guide is relative to the base URL:

Base URL
https://<api host>/v1/partner

The API host is given to you together with your API key. Requests and responses are JSON over HTTPS (the token call also accepts a form body).

Payment. Tickets are paid from your organisation wallet; no card data passes through the API. Your wallet is charged only when a ticket is issued, never for a search, a price or a hold. Voids and refunds go back to the same wallet. You see your balance and your bookings in your dashboard.

Which airlines you can sell and your limits are set for your account by Flyzafy.

Authentication

The API uses the OAuth 2 client-credentials flow. Your API key looks like fz_live_<id>.<secret>: the part between fz_live_ and the first dot is your client ID, the part after the dot is your client secret. The console shows both when it shows the key.

  1. Exchange them for an access token with POST /security/token (form-encoded, as below, or JSON with the same fields).
  2. Send the token on every other call: Authorization: Bearer <access_token>.
  3. Reuse the token until it expires (expires_in seconds, 30 minutes). When a call answers 401 INVALID_TOKEN, get a new token and retry once.
Get a token
export BASE="https://<api host>/v1/partner"

# Your key fz_live_<id>.<secret>: client_id = <id>, client_secret = <secret>
curl -X POST "$BASE/security/token" \
  -d grant_type=client_credentials \
  -d client_id=<id> \
  -d client_secret=<secret>
Response
{
  "token_type": "Bearer",
  "access_token": "fzt_3qQm…",
  "expires_in": 1799,
  "scope": "flights:search flights:book flights:manage bookings:read"
}
Use the token
export TOKEN="fzt_3qQm…"

curl "$BASE/flights/offers?origin=JFK&destination=LHR&departureDate=2026-12-10&adults=1" \
  -H "Authorization: Bearer $TOKEN"
  • Sending the API key itself as the Bearer is refused (401 INVALID_TOKEN).
  • A wrong client ID, a wrong secret and a revoked key all get 401 INVALID_CLIENT. The token call allows 30 requests a minute per IP address (429 RATE_LIMITED).
  • Every call checks the key behind the token again: revoking the key, or switching your API access off, stops its tokens at once.
  • Create keys in the console under API keys. The full key is shown once, when it is created; store it in your secret manager. We keep only a hash and cannot show it again.
  • Use keys and tokens from your servers only. Never put them in a browser or mobile app.
  • If a key leaks, revoke it in the console at once and create a new one.

Get an access token

The authentication call. Form-encoded (as above) or JSON with the same three fields. The answer is the token, its lifetime in seconds and the key’s permissions.

Loading the example…

Scopes

Each key carries the scopes you choose; its tokens carry the same scopes (listed in scope). A call to an endpoint whose scope the key lacks is refused with INSUFFICIENT_SCOPE. Give each key only what that system needs.

ScopeAllows
flights:searchSearch, price and seat maps
flights:bookBook and issue flights
flights:manageChange and cancel flight bookings
bookings:readRead bookings
webhooks:manageManage webhooks

IP allowlist, expiry and rotation

  • IP allowlist. A key can be limited to IPv4/IPv6 addresses and CIDR ranges. An empty list allows any address. The token call and every other call from another address are refused with IP_NOT_ALLOWED (the message names the address we saw).
  • Expiry. A key can have an expiry date. After it, the key and its tokens are refused with API_KEY_EXPIRED.
  • Rotation with overlap. Rotating a key creates a new key and keeps the old one working for an overlap window you choose (default 24 hours, up to 168 hours, 0 = it stops at once). Deploy the new key, then let the old one expire.

Conventions

  • Send Content-Type: application/json with every request body. Unknown fields are refused.
  • X-Request-Id: send your own correlation id (letters, digits, . _ -, up to 100 characters) or let us generate one. It is returned on every reply and inside every error. Quote it when you contact support.
  • Dates are YYYY-MM-DD. Flight times are local at the airport. Timestamps we return are ISO 8601 in UTC.
  • A booking can be addressed by our id, its 12-digit reference or its pnr.

Errors

Every error has the same shape. code is stable and meant for your code; message is for people and may change. details is present only for some codes.

Error response
HTTP/1.1 409 Conflict
X-Request-Id: 2c7e0f0a-6a5e-4f7b-9a43-0b2d1f1c9e11

{
  "error": {
    "code": "PRICE_CHANGED",
    "message": "The airline changed the price. Nothing was booked.",
    "requestId": "2c7e0f0a-6a5e-4f7b-9a43-0b2d1f1c9e11",
    "details": { "expectedTotal": 642.3, "newTotal": 655.1, "currency": "USD" }
  }
}

Error codes

Getting a token (POST /security/token)

CodeHTTPMeaningWhat to do
INVALID_REQUEST400grant_type, client_id or client_secret is missing. details.missing lists them.Send all three fields.
UNSUPPORTED_GRANT_TYPE400grant_type is not client_credentials.Send grant_type=client_credentials.
INVALID_CLIENT401The client ID or secret is wrong, or the key was revoked (all get the same answer).Check the values; create a new key in the console if it was revoked.
RATE_LIMITED429More than 30 token requests a minute from your IP address. Retry-After is set.Reuse your token until it expires instead of asking for a new one per call.

Access (token call and every other call)

CodeHTTPMeaningWhat to do
UNAUTHORIZED401No Authorization header, or not in the form Bearer <token>.Send Authorization: Bearer <access token>.
INVALID_TOKEN401The access token is unknown or expired, or its key was revoked. Sending the API key itself as the Bearer also gives this.Get a new token from POST /security/token and retry once.
API_KEY_EXPIRED401The key passed its expiry, or the overlap window after a rotation ended.Switch to the replacement key.
MERCHANT_SUSPENDED403API access for your organisation is suspended. Every key is refused; nothing is deleted.Contact your account manager.
MERCHANT_INACTIVE403Your organisation is not active.Contact your account manager.
API_ACCESS_DISABLED403API access is switched off for your organisation.Contact your account manager.
IP_NOT_ALLOWED403The request came from an address that is not on the key’s IP allowlist.Add the address (or its range) to the key’s allowlist in the console.
INSUFFICIENT_SCOPE403The key lacks the permission this endpoint needs. details.requiredScope names it.Edit the key’s scopes in the console, or use a key that has it.
PRODUCT_NOT_ENABLED403Flights are not enabled for your account.Ask your account manager to enable them.
RATE_LIMITED429A per-minute, per-day or search limit was reached. details.retryAfterSeconds and details.limit are set.Wait for Retry-After seconds, then retry.

Request

CodeHTTPMeaningWhat to do
INVALID_REQUEST400The body or query is not valid. details.fields lists each problem when there are several.Fix the request. Do not retry unchanged.
IDEMPOTENCY_KEY_REQUIRED400This request creates or changes a booking and has no Idempotency-Key header.Send a unique Idempotency-Key.
INVALID_IDEMPOTENCY_KEY400The Idempotency-Key is not 8–128 letters, digits or . _ : -Use a UUID or a similar value.
IDEMPOTENCY_KEY_REUSED409The key was already used on this endpoint with a different body.Use a new key for a new request.
IDEMPOTENCY_IN_PROGRESS409A request with this key is still running.Wait a few seconds and retry with the same key.
UNKNOWN_TRAVELER400A travelerId is not on the priced offer or the booking.Use the travelerId values of offer.fares.
CONTACT_EMAIL_<problem>400The booking contact email was refused. <problem> is EMPTY, FORMAT, TOO_LONG, DISPOSABLE or NO_MAIL_DOMAIN.Ask the traveller for a working, non-disposable address.
CONTACT_PHONE_<problem>400The booking contact phone was refused. <problem> is EMPTY, FORMAT, INVALID or NOT_MOBILE.Send a mobile number in international format, e.g. +14155550123.

Search and price

CodeHTTPMeaningWhat to do
NO_ALLOWED_AIRLINE422None of the airlines in includeAirlines is enabled for your account.Search without the filter, or with airlines you are allowed to sell.
AVAILABILITY_NOT_ENABLED422No content with an availability search is enabled for your account.Use flight search instead, or ask your account manager.
OFFER_EXPIRED404The offerId is unknown or its search is older than 20 minutes.Search again.
OFFER_NOT_AVAILABLE422The airline no longer sells this offer at pricing time.Pick another offer or search again.
PRICED_OFFER_EXPIRED404The pricedOfferId is unknown or expired.Price the offer again (search again if the offer also expired).
EXTRAS_REFUSED422The airline did not accept the seats or bags asked for.Read the message; try other seats or fewer bags.

Book (POST /flights/bookings)

CodeHTTPMeaningWhat to do
AIRLINE_NOT_ENABLED403The priced flight uses an airline not enabled for your account.Choose another offer.
HOLD_NOT_ALLOWED422This fare cannot be held (no ticketing deadline, instant ticketing required, or too little time left).Book with ticketing ISSUE, or choose another fare.
PRICE_CHANGED409The airline’s price differs from expectedTotal. Nothing was booked. details: expectedTotal, newTotal, currency.Show the new price; if accepted, price again and book with the new expectedTotal.
BOOKING_LIMIT_EXCEEDED422The amount is above your single-booking limit (also checked at issue).Contact your account manager to change the limit.
DAILY_BOOKING_LIMIT429Your bookings-per-day limit is reached. It resets at midnight UTC.Retry after midnight UTC, or ask for a higher limit.
HOLD_LIMIT_REACHED429You have as many open (not issued) holds as your limit allows.Issue or cancel a hold first.
INSUFFICIENT_BALANCE402The wallet cannot pay. Nothing was charged.Top up the wallet, then retry.
BOOKING_REFUSED422The airline or our checks refused the booking. The message says why.Read the message; do not retry unchanged.

Issue (POST /flights/bookings/{id}/issue)

CodeHTTPMeaningWhat to do
NOT_ISSUABLE422The booking is already ticketed, cancelled, or has no airline record.Read the booking.
HOLD_EXPIRED422The hold passed its release time and is being cancelled.Search and book again.
ISSUE_IN_PROGRESS409This booking is already being issued.Read the booking again in a moment.
PRICE_CHANGED409The airline’s price for the booking changed since it was made. Nothing was charged; the hold stays. details: airlineTotalAtBooking, airlineTotalNow.Cancel the hold and book again.
INSUFFICIENT_BALANCE402The wallet does not cover the ticket. Nothing was charged; the hold stays.Top up and issue again.
TICKETING_REFUSED422The airline refused the ticket. Nothing was charged; the booking is still held.Read the message; contact support if it repeats.
AIRLINE_UNAVAILABLE502The airline system did not answer before issuing. Nothing was charged.Try again in a moment.

Read, change and cancel

CodeHTTPMeaningWhat to do
BOOKING_NOT_FOUND404No such booking on your account (id, reference or PNR).Check the value you sent.
NOT_BOOKED409The booking has no airline record (yet, or any more).Read the booking.
AIRLINE_RECORD_UNAVAILABLE502The airline system did not answer.Try again in a moment. After a document update, read the booking to see whether it was applied.
SEATS_REFUSED422The seats could not be added (for example the booking is already ticketed).Read the message.
SEAT_OUTCOME_UNKNOWN503The airline gave no clear answer about the seats.Read the booking before trying again.
DOCUMENTS_REFUSED422The airline did not accept the travel documents.Check the document details.
AIRLINE_BUSY409The airline is still processing a change to this booking. Nothing was changed. details.retryAfterSeconds is set.Retry in about 30 seconds.
CANCEL_REFUSED422The booking cannot be cancelled now.Read the message; contact support if needed.

General

CodeHTTPMeaningWhat to do
FORBIDDEN / NOT_FOUND / CONFLICT403 / 404 / 409Generic codes when no more specific code applies.Read the message.
PAYLOAD_TOO_LARGE413The request body is too large.Send a smaller body.
INTERNAL_ERROR500Something failed on our side.Retry later. On a booking request, read the booking before retrying. Quote the requestId to support.
SUPPLIER_ERROR / UNAVAILABLE / SUPPLIER_TIMEOUT502 / 503 / 504The airline system or our service is unavailable.Retry later with backoff. Quote the requestId to support.

Idempotency

Every request that creates or changes a booking needs an Idempotency-Key header: 8–128 letters, digits or . _ : - (a UUID works). These are book, issue, update and cancel, marked in the endpoint reference.

  • A retry with the same key and the same body returns the first result, with the header Idempotent-Replayed: true. Successful results are kept for 24 hours.
  • The same key with a different body is refused: 409 IDEMPOTENCY_KEY_REUSED.
  • A retry while the first request is still running gets 409 IDEMPOTENCY_IN_PROGRESS; wait and retry with the same key.
  • A failed request is not stored, so it can be retried with the same key.
Generate the key once per intended action (for example per customer order) and reuse it for every retry of that action. If your request times out, retry with the same key: a finished booking is replayed, a running one is not started twice.

Rate limits

Limits are per merchant: requests per minute, requests per UTC day, and a lower per-minute limit for searches (flight search and availability). Ask your account manager for your values.

HeaderMeaning
RateLimit-LimitRequests allowed in the current minute.
RateLimit-RemainingRequests left in the current minute.
RateLimit-ResetSeconds until the minute window resets.
Retry-AfterOn a 429 only: seconds to wait before retrying.

A refused request gets 429 RATE_LIMITED. The daily limit resets at midnight UTC. Separate from request limits, your account may have a bookings-per-day limit (DAILY_BOOKING_LIMIT), a maximum amount per booking (BOOKING_LIMIT_EXCEEDED) and a maximum number of open holds (HOLD_LIMIT_REACHED).

Money

Amounts in responses are decimal strings with two decimals, for example "1042.80", always with a currency next to them. Parse them with a decimal type, not a float. Amounts you send (expectedTotal) are JSON numbers. Prices are in USD.

StepYour wallet
Search, availability, price, upsell, seat maps, extrasNothing.
Book with ticketing HOLDNothing charged, nothing held.
Issue (or book with ticketing ISSUE)The price is charged when the ticket is issued. If the airline refuses the ticket, nothing is charged and the booking stays a hold.
Cancel a hold that was never issuedNothing to give back.
Cancel an issued booking inside the void windowVoided: everything back to the wallet.
Cancel an issued booking after the void windowCancelled; the refund (fare minus the airline penalty) reaches the wallet after the airline has processed it.

The price you get is your price, including paid seats and extra bags you added; add your own margin for your customers.

Pending bookings (PENDING_CONFIRMATION)

If the airline gives no clear answer while booking or issuing, we do not guess. The booking is returned with status PENDING_CONFIRMATION, any money stays held in your wallet, and our team settles it with the airline. An issue that the airline has not confirmed yet comes back with issue.status PENDING: the amount is charged and issuance is retried. Read the booking again later, or subscribe to booking.ticketed.

Do not book the same trip again while a booking is pending.

Flights

The flow is search → price → (fare families, seat maps, seats and bags) → book → issue, then read, change or cancel the booking. Each call below shows a real request and the real answer from our test system; the API reference describes every field.

Search flights (GET)

One-way or return search as query parameters: origin, destination, departureDate, and returnDate for a return. Lists are comma-separated (includeAirlines=EK,QR). Prices are your selling price. Offers stay usable for 20 minutes (expiresAt); offers with the same flights share a groupId (the fare families of one flight).

Loading the example…

Seat availability

The flights on 1–6 slices (each with an optional earliest departureTime) with the seats left in every booking class. No prices and nothing bookable — use Search flights to sell.

Loading the example…

Price an offer

Prices one offer with the airline now (never from a cache). No request body. The answer has the pricedOfferId you book with, the fare’s penalties and fareRules, the extra bags the airline sells (bagOptions), what the airline needs from the travellers (bookingRequirements) and whether the fare can be held (holdAllowed). Show offer.price.total and send it as expectedTotal when you book.

Loading the example…

Get a priced offer

The priced offer again (with any seats and bags added), without a new airline call, until it expires (PRICED_OFFER_EXPIRED).

Loading the example…

Fare families (upsell)

The other fare families (brands) of the same flights — e.g. Saver, Flex, Plus — each a new offer with its own offerId and selling price, in the search shape. Price the one your customer picks to get its pricedOfferId.

Loading the example…

Seat maps of an offer

Every seat of every flight with its status and selling price per traveller. Some airlines show seats only after ticketing: then available is false with the reason.

Loading the example…

Add seats and bags

Re-prices the same pricedOfferId with paid seats from its seat map (seats[]: travelerId, segmentId, seatNumber) and/or extra checked bags (bags[]: travelerId, quantity 1–5, on every flight). The answer is the priced offer at the new total, with extras; a seat the airline did not price is left out and listed in droppedSeats. Sending the call again replaces the choice; an empty body removes it. Then book with the new expectedTotal.

Loading the example…

Book a flight

Books the priced offer with the airline. Requires an Idempotency-Key. ticketing decides what happens next:

  • HOLD — booked, not issued, nothing charged. Issue it later. Only for fares where holdAllowed.allowed is true (otherwise 422 HOLD_NOT_ALLOWED). A hold that is not issued is cancelled automatically at holdReleaseAt, before the airline’s ticketing deadline.
  • ISSUE — booked and issued in one call; the wallet is charged when the ticket is issued. The result is in issue. If issuing is refused, the booking is still made and stays a hold: issue.status is REFUSED with a code.
FieldRequiredNotes
pricedOfferIdyesFrom Price an offer (or Add seats and bags).
ticketingyesHOLD or ISSUE.
expectedTotalyesThe total you agreed to. If the airline’s price moved, the booking is refused with 409 PRICE_CHANGED and nothing is booked.
travelers[]yes1–9 travellers. id is the travelerId from the priced offer’s fares.
travelers[].title, firstName, lastName, gender, dateOfBirthyesgender: MALE or FEMALE. dateOfBirth: YYYY-MM-DD.
travelers[].middleName, passportNumber, documentExpiryDate, nationality, issuanceCountry, documentType, issuanceDate, birthPlace, issuanceLocationwhen the airline needs themCountries are ISO 2-letter codes. Check bookingRequirements.
contact.name, email, phoneyesphone: a mobile number in international format. Disposable or undeliverable emails are refused.
contact.addressno{ lines[], postalCode, cityName, countryCode, stateName }.
merchantReferencenoYour own reference (letters, digits, . _ : -, up to 64), returned on the booking.

Loading the example…

booking.statusMeaning
CONFIRMEDBooked with the airline. With ticketStatus NOT_TICKETED it is a hold (or the ticket is being issued).
PENDING_CONFIRMATIONThe airline gave no clear answer; our team settles it.
TICKETEDTickets issued (see tickets[]).
CANCELLEDCancelled with the airline.
VOIDEDVoided; the money went back to the wallet.
REFUNDEDRefunded to the wallet.
FAILEDNot booked.

price.total is the booking’s price (paid seats included); price.charged what your wallet has paid so far (0.00 until the ticket is issued).

Issue the ticket

Issues a hold and charges your wallet. Requires an Idempotency-Key. No request body.

  1. The booking is read again from the airline. If the airline’s price changed since it was booked, issue is refused with 409 PRICE_CHANGED; nothing is charged.
  2. The amount is held on your wallet (402 INSUFFICIENT_BALANCE if it does not cover it).
  3. Issued → the amount is charged (issue.status ISSUED). Refused by the airline → released, nothing charged (422 TICKETING_REFUSED), the booking stays held. Not confirmed yet → PENDING: charged, issuance retried; the booking shows TICKETED once the ticket exists.

Loading the example…

Get a booking

By our id, the 12-digit reference or the pnr. Returns our booking and the airlineRecord read live from the airline: the linked record locators, the travellers, each flight with its current status (a schedule change or an airline cancellation shows here first) and each ticket with its status. airlineRecord.found is false once the airline no longer holds the record. include=bags adds bagOptions; fareRules=refunds,rebooks adds airlineFareRules.

Loading the example…

Get a booking by PNR

The same answer, looked up by the airline record locator. Only your own bookings are found.

Loading the example…

Seat maps of a booking

Seat maps of the booked flights. While the booking is held and unpaid, paid seats show their selling price and canAddSeats is true; addSeatsNote says why not otherwise.

Loading the example…

Add seats or documents

Exactly the two changes the airline API allows; send one or both. Requires an Idempotency-Key.

  • seats[] — paid seats, only before the ticket is issued. The seat’s price is added to the booking, so the amount charged at issue grows. Free seats are chosen at check-in.
  • travelers[] (id, documents[]) — travel documents: documentType (PASSPORT, IDENTITY_CARD, VISA), number, expiryDate, issuanceCountry, nationality; optional issuanceDate, issuanceLocation, birthPlace, holder.

Loading the example…

Cancel a booking

Requires an Idempotency-Key. No request body. cancellation in the answer says what happened:

BookingcancellationMoney
Not issued (a hold)type CANCEL, refund NONENothing was charged.
Issued, inside the void windowtype VOID, refund FULLEverything back to your wallet.
Issued, after the void windowtype CANCEL, refund AFTER_AIRLINE_REFUNDThe refund (fare minus the airline penalty) reaches your wallet after the airline has processed it.

Right after issuing, the airline may still be busy: 409 AIRLINE_BUSY — retry after details.retryAfterSeconds.

Loading the example…

Webhooks

Webhooks tell your server when something changes, so you do not have to poll. Add up to 5 endpoints, each with its own events and signing secret. Endpoints must be public https:// addresses; redirects are not followed and each delivery times out after 10 seconds. Manage them in the console (API access → Webhooks: add, edit, pause, send a test, new secret, and every delivery with its answer and a resend button) or through the API (scope webhooks:manage) — both change the same endpoints.

Add an endpoint
curl -X POST "$BASE/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/flyzafy",
    "events": ["booking.ticketed", "booking.cancelled", "booking.voided"]
  }'

# → 201 { "id": "…", "url": "…", "status": "ACTIVE", "events": [ … ],
#          "secretLast4": "…", "secret": "<shown once — store it now>", … }

events lists the event names to receive; omit it or send ["*"] for all. The secret is returned only in this answer and by POST /webhooks/{id}/rotate-secret. Pause an endpoint with PATCH /webhooks/{id} and { "status": "DISABLED" }.

Events

EventSent when
booking.createdA flight booking was created.
booking.ticketedTickets were issued for a flight booking.
booking.ticketing_failedTicket issuance failed; our team follows up.
booking.ticketing_partialSome tickets of a booking were issued and others were not; the booking is held for our team.
booking.failedA flight booking failed.
booking.attach_failedThe airline record exists but could not be saved on our side; our team reconciles it.
booking.queue_alertThe airline changed something on the booking (schedule change, ticketing time limit).
booking.exchange_requestedA date or route change was requested.
booking.cancelledA flight booking was cancelled.
booking.cancellation_requestedA cancellation was requested and waits for our team.
booking.voidedA flight booking was voided.
booking.refundedMoney for a flight booking was refunded.

Each delivery is a POST with a JSON body { id, event, data, created_at }. data depends on the event and identifies the booking (order id, reference, PNR, status). Read the booking through the API for its full state.

Example delivery
POST /hooks/flyzafy HTTP/1.1
Content-Type: application/json
User-Agent: Flyzafy-Webhooks/1
Webhook-Id: evt_5b1f0c7e2d9a4c3b8e6f1a2b3c4d5e6f
Webhook-Timestamp: 1763114400
Webhook-Signature: v1=4f8e…c21a

{
  "id": "evt_5b1f0c7e2d9a4c3b8e6f1a2b3c4d5e6f",
  "event": "booking.ticketed",
  "data": { "order_id": "c1a2b3d4-…", "booking_reference": "482915307162", "pnr": "ABC123" },
  "created_at": "2026-11-18T10:00:00.000Z"
}

Verifying signatures

HeaderMeaning
Webhook-IdThe event id (same as id in the body). Use it to de-duplicate.
Webhook-TimestampUnix time in seconds when this attempt was sent.
Webhook-Signaturev1=<hex HMAC-SHA256(secret, "<Webhook-Id>.<Webhook-Timestamp>.<raw body>")>

Compute the HMAC over the raw request body (not a re-serialised object), compare in constant time, and refuse timestamps more than 5 minutes away from your clock.

Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.FLYZAFY_WEBHOOK_SECRET; // from POST /webhooks or rotate-secret
const TOLERANCE_SECONDS = 5 * 60;

const app = express();

// Keep the RAW body: the signature covers the exact bytes we sent.
app.post('/hooks/flyzafy', express.raw({ type: 'application/json' }), (req, res) => {
  const id = req.header('Webhook-Id');
  const timestamp = req.header('Webhook-Timestamp');
  const signature = req.header('Webhook-Signature') ?? '';
  const rawBody = req.body.toString('utf8');

  if (!id || !timestamp || !signature.startsWith('v1=')) {
    return res.status(400).send('missing signature headers');
  }
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) {
    return res.status(400).send('timestamp outside tolerance');
  }

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest('hex');
  const given = signature.slice(3);
  const ok =
    given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given, 'hex'), Buffer.from(expected, 'hex'));
  if (!ok) return res.status(400).send('bad signature');

  const event = JSON.parse(rawBody);
  // De-duplicate on Webhook-Id (= event.id): a retry or a resend carries the same id.
  // Answer 2xx quickly, then do the work in the background.
  res.sendStatus(200);
  handleEvent(event);
});

Retries, resend and test

  • Answer with any 2xx status to acknowledge. Anything else, a timeout or a redirect is a failure.
  • A failed delivery is retried after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h, for up to 24 hours from the event; then it is marked FAILED. Each retry has the same Webhook-Id and a new timestamp and signature.
  • GET /webhook-deliveries (filter status: PENDING, DELIVERED, FAILED) and GET /webhook-deliveries/{id} show what was sent and the last error.
  • POST /webhook-deliveries/{id}/resend sends a delivered or failed event again with the same event id.
  • POST /webhooks/{id}/test sends a webhook.test event to that endpoint once (not retried) and returns the delivery result.

Endpoint reference

All paths are relative to https://<api host>/v1/partner. The full API reference describes every parameter and field with real request and response examples, and lets you try the read-only calls with your key. You can also download the OpenAPI 3.1 document and load it into your API client or code generator.

Authentication

MethodPathPurposeScopeIdempotency-Key
POST/security/tokenExchange your client ID and secret for an access token (30 minutes)——

Flight shopping

MethodPathPurposeScopeIdempotency-Key
GET/flights/offersSearch flights (one-way or return, query string)flights:search—
POST/flights/offers/searchSearch flights (one-way, return or multi-city)flights:search—
POST/flights/availabilitySeats left per booking class (no prices)flights:search—
POST/flights/offers/{offerId}/priceLive price of one offer → pricedOfferIdflights:search—
GET/flights/priced-offers/{pricedOfferId}Read a priced offer againflights:search—
POST/flights/priced-offers/{pricedOfferId}/extrasRe-price with paid seats and/or extra bagsflights:search—
POST/flights/priced-offers/{pricedOfferId}/upsellOther fare families of the same flightsflights:search—
GET/flights/priced-offers/{pricedOfferId}/seatmapsSeat maps with seat pricesflights:search—

Flight bookings

MethodPathPurposeScopeIdempotency-Key
POST/flights/bookingsBook a priced offer (ticketing HOLD or ISSUE)flights:bookrequired
POST/flights/bookings/{id}/issueIssue the tickets of a hold (charges the wallet)flights:bookrequired
GET/flights/bookings/{id}One booking, with the airline record read live (by id, reference or PNR)bookings:read—
GET/flights/bookings/by-reference/{pnr}One booking by its record locator (PNR)bookings:read—
GET/flights/bookings/{id}/seatmapsSeat maps of a booked flightbookings:read—
PATCH/flights/bookings/{id}Add paid seats (before issue) and/or travel documentsflights:managerequired
DELETE/flights/bookings/{id}Cancel (a ticket inside the void window is voided)flights:managerequired

Webhooks

MethodPathPurposeScopeIdempotency-Key
GET/webhooksYour webhook endpoints and the events you can subscribe towebhooks:manage—
POST/webhooksAdd an endpoint (the signing secret is shown once)webhooks:manage—
PATCH/webhooks/{id}Change an endpoint (url, events, status)webhooks:manage—
DELETE/webhooks/{id}Remove an endpointwebhooks:manage—
POST/webhooks/{id}/rotate-secretNew signing secret (shown once)webhooks:manage—
POST/webhooks/{id}/testSend a webhook.test event nowwebhooks:manage—
GET/webhook-deliveriesRecent deliveries (filter: status, limit)webhooks:manage—
GET/webhook-deliveries/{id}One delivery with its payloadwebhooks:manage—
POST/webhook-deliveries/{id}/resendSend a delivery again (same event id)webhooks:manage—

This page: /docs