A travel site can send thousands of visitors to booking pages and still produce weak affiliate revenue. The missing piece is often a controlled Travelpayouts API connection, not more traffic.
Travelpayouts has several APIs for different jobs. Pick the right one, keep credentials off the client, test a small request, then record approved results. Start with the API product that matches the decision you need to make.
CHOOSE THE RIGHT TRAVELPAYOUTS API FIRST
Don’t treat Travelpayouts as one large API with one universal response. Its products cover reporting, partner-link creation, flight search, and flight-price data. Each product can have different access rules, request limits, and authentication requirements.
Use statistics data for affiliate reporting
The statistics API is for booking and affiliate program data. Use it when you need to build an internal earnings dashboard, reconcile program results, or compare campaign performance.
The documented workflow starts with get_fields_list. That request shows the fields available to your account before you build a query. You can then send a POST request to execute_query with fields and filters that match the report you need.
Read the Travelpayouts statistics API documentation before you write a report query. Available fields can differ by program and report type.
Use flight search only when your product needs it
The flight search API fits a website that needs a real search flow. A visitor enters route and passenger details. Your application receives a unique search ID, then uses that ID to request results and prices.
This product isn’t an automatic add-on for every account. Travelpayouts asks partners to request access and provide a website URL, search-results prototypes, and a reason standard tools don’t fit the product. Review the current flight search API access rules before you build around it.
Use a hosted widget or affiliate link when it meets the page requirement. Build a custom search flow only when your team can support search state, rate limits, error handling, and referral tracking.
CREATE A PROJECT AND STORE THE TOKEN SAFELY
You need a Travelpayouts publisher account and a project connected to your real website. Join the affiliate programs you plan to promote before you expect program-level data or valid partner links.
Travelpayouts places the API token in your account under Profile -> API token. For the statistics API, send that token in the X-Access-Token request header.
Keep the token on your server
Never place an API token in browser JavaScript, a public Git repository, a CMS page, or a mobile app bundle. A visitor can inspect all of those locations.
Store the value in your hosting provider’s secrets manager or encrypted environment-variable store. Give production and staging separate tokens when your account setup allows it. Restrict access to people who maintain the integration.
Use variables your team can recognize:
| Variable | Store | Purpose |
|---|---|---|
TRAVELPAYOUTS_API_TOKEN | Secret manager | Sends authenticated server-side requests |
TP_STATS_BASE | Server configuration | Points to the documented statistics API base URL |
TP_CAMPAIGN_ID | Server configuration | Holds the program ID used in a report |
TP_REQUEST_TIMEOUT_MS | Server configuration | Stops stalled outbound requests |
Don’t log TRAVELPAYOUTS_API_TOKEN. Redact the X-Access-Token header in error tools such as Sentry, Datadog, or your server logs.
Separate configuration from code
Your repository should contain variable names, not secret values. Add .env files to .gitignore. Keep a .env.example file with empty values so another developer knows what the service requires.
Rotate the token if it appears in a commit, support ticket, screenshot, or shared document. Remove the exposed secret before treating the incident as closed.
MAKE YOUR FIRST AUTHENTICATED REQUEST
Start with a read-only request. The statistics field-list endpoint is a good test because it doesn’t create a booking link or change account data.
Set TP_STATS_BASE to the documented Statistics API base URL in your server environment. Then run this request from a terminal where the token is available:
curl --silent --show-error --fail-with-body -H "X-Access-Token: $TRAVELPAYOUTS_API_TOKEN" "$TP_STATS_BASE/get_fields_list?data_type=aggregated" -o fields.json
The data_type=aggregated option requests aggregated reporting fields. Save the result as fields.json, then inspect the JSON before you create a dashboard query.
You can also request fields for a known campaign ID:
curl --silent --show-error --fail-with-body -H "X-Access-Token: $TRAVELPAYOUTS_API_TOKEN" "$TP_STATS_BASE/get_fields_list?campaign_id=$TP_CAMPAIGN_ID" -o campaign-fields.json
Travelpayouts uses program IDs in its reporting workflow. The documentation uses Aviasales program ID 100 and Booking.com program ID 84 as examples. Don’t hard-code those values unless they are the programs connected to your account.
Check the result before building a report
A successful HTTP response isn’t enough. Open the saved JSON and confirm it contains the field definitions your report needs.
Don’t guess field names from an old blog post or another affiliate program. Query the field list first. Then map only the returned fields into your database or reporting layer.
The API returns JSON, but values, available columns, and program rules can change. Keep a copy of the raw response with the retrieval date when you change your mapping.
HANDLE RESPONSES AND ERRORS IN JAVASCRIPT
Keep Travelpayouts calls inside a server route, background worker, or backend service. A Next.js route handler, Express application, Cloudflare Worker, or Laravel backend can all make the request. The browser should call your own application, not Travelpayouts directly.
Inside an async server function, use a small request wrapper:
const endpoint = process.env.TP_STATS_BASE + "/get_fields_list?data_type=aggregated";const response = await fetch(endpoint, { headers: { "X-Access-Token": process.env.TRAVELPAYOUTS_API_TOKEN } });const body = await response.text();if (!response.ok) throw new Error("Travelpayouts returned " + response.status + ": " + body.slice(0, 500));let payload; try { payload = JSON.parse(body); } catch { throw new Error("Travelpayouts returned non-JSON content"); }
This pattern reads the response body once. It also preserves useful error content without dumping an unlimited response into your logs.
Classify failures before retrying
A 401 or 403 response usually needs a token, account, or access review. Retrying it ten times does nothing.
A 429 means your service sent too many requests. Pause the queue and wait for the documented reset period. A 500-class response can be temporary. Retry it a limited number of times with increasing delays.
Set a timeout for every outbound request. A stalled API call shouldn’t hold a web request open until your hosting platform kills it.
Store the request date, endpoint group, HTTP status, campaign ID, and retry count. Do not store the token or visitor data you don’t need.
CREATE AFFILIATE LINKS WITH THE PARTNER LINKS API
The partner links API converts approved direct travel-brand URLs into your affiliate links. This fits editorial workflows where your CMS already contains destination pages, hotel references, or travel brand links.
The documented endpoint is POST /links/v1/create. Use the exact request format shown in the official partner links API documentation, because supported request details can change.
Validate each source URL
Send full-length direct brand URLs. Don’t send shortened links. Travelpayouts limits a request to no more than 10 links.
Not every brand supports this conversion method. The current restrictions include Kiwi.com, Expedia UK, HolidayTaxis, Ticketmaster, Priority Pass, and Indrive. Check the live documentation before you add a conversion job to your publishing process.
Run conversion in a staging table first. Keep these records for each link:
- The original destination URL and the converted affiliate URL.
- The Travelpayouts project, program, page URL, and placement label.
- The conversion date, API result, and reviewer decision.
- The page owner who will fix a failed or outdated link.
A clean-looking affiliate URL doesn’t prove it opens the right booking page. Test the live destination on desktop and mobile after publishing.
Track placement with a naming system
Use a readable SubID or internal placement label where the program supports it. Names such as rome-guide-flight-top, rome-guide-hotel-midpage, and email-summer-car-rental show what created the result.
Avoid generic labels like banner1 or campaign-new. Six months later, no one will know what they mean.
If a complex integration needs a defined ownership plan, staging process, and reporting model, Book A Call before your team connects production traffic.
CONTROL RATE LIMITS, CACHING, AND RETRIES
Rate limits are part of the Travelpayouts API design. Don’t wait for 429 errors before you plan for them.
Travelpayouts publishes limits by endpoint. For example, the documented limit for statistics/v1/execute_query is 30 requests per minute. Several flight-price endpoints allow higher request volumes. Check the current API rate limits before setting worker concurrency.
Read the response headers
Travelpayouts documents three useful headers:
X-Rate-Limitshows the limit for that request type.X-Rate-Limit-Remainingshows requests left in the current window.X-Rate-Limit-Resetshows seconds until the window resets.
When remaining requests drop low, reduce concurrency. When the reset value is positive after a 429, pause the affected queue before retrying.
Don’t run one API request for every page view. Cache report metadata. Cache stable flight-price data for a period that fits the product. Use server-side queues for scheduled imports.
Ticket search has a separate default limit of 200 requests per hour from one IP address. That limit can be changed by Travelpayouts, but don’t assume an exception before you receive one.
Keep a last trusted result
A failed import shouldn’t erase yesterday’s data. Save each completed run with a run ID, timestamp, source endpoint, record count, and status.
Keep the last successful export available. If Travelpayouts changes a schema or access rule, stop the write step and review the raw response. Don’t let a background job replace valid earnings data with empty rows.
MEASURE APPROVED EARNINGS, NOT API ACTIVITY
API calls, click totals, and pending bookings are not affiliate revenue. A booking can cancel, reverse, fail a program condition, or lose attribution before approval.
Your Travelpayouts API connection should feed a decision record, not a dashboard full of numbers nobody uses.
Build a fixed earnings record
Create one row per content source, program, and reporting period. Store the content URL, traffic source, program, offer, placement label, clicks, bookings, pending rewards, approved rewards, reversals, payout date, and payment method.
Use a simple calculation:
Net affiliate earnings = approved percentage rewards + approved fixed rewards - reversals
Keep the original row when an amount changes. Add a separate correction row with the reversal reason and review date. Don’t overwrite history.
A page with 1,000 clicks and $30 in approved rewards is weaker than a page with 120 clicks and $48 in approved rewards. Review approved earnings and eCPC by page before you buy more traffic or publish another broad guide.
IMPLEMENTATION CHECKLIST
Before you send production traffic through the integration, confirm each item:
- Your account, project, and required affiliate programs are active.
- The API token lives only in server-side secrets storage.
- Your first field-list request returns valid JSON.
- Your code checks HTTP status before it parses or saves data.
- Retry logic handles temporary failures but stops on access and schema problems.
- Your worker reads rate-limit headers and limits concurrency.
- Partner links use full direct URLs and pass a live destination test.
- Reports separate pending, approved, reversed, and paid amounts.
- Each import preserves the prior trusted result and writes a run record.
FINAL THOUGHTS
A working Travelpayouts API integration is controlled work. It starts with the right product, a protected token, a small authenticated request, and a reporting record that survives reversals.
API access, authentication rules, available fields, brand support, and limits can change. Recheck the live Travelpayouts documentation before each major release, then measure approved earnings instead of counting requests or clicks.
