Pre-integration checklist for supplier APIs: data fields, test cases and reconciliation smoke-tests

You've signed the contract with Hotelbeds or Viator. Maybe it's a smaller regional supplier with flights across Southeast Asia. The sales team promised seamless integration, your tech person says the documentation looks straightforward, and everyone's excited about the expanded inventory. Then three weeks post-launch, you discover the API has been sending room rates in EUR while displaying them as USD on your site. Or worse—availability data shows hotels as bookable that were actually sold out, leading to angry clients and manual rebooking scrambles at 11 PM. The gap between "API connected successfully" and "API actually working for our business" destroys more travel agency operations than almost any other technical issue. Not because APIs are inherently broken, but because agencies skip the unglamorous validation work that catches these problems before clients see them.

Why standard API testing misses operational reality

Most integration guides focus on whether data flows between systems. Can we receive inventory? Check. Can we send booking requests? Check. Integration complete.

Travel operations need something different. You need to know if that "Deluxe Ocean View" room from supplier A matches the "DLX-OV" category from supplier B. Whether their definition of "confirmed" aligns with what you tell clients. If their cancellation windows account for time zones the same way you do.

Technical integration tests verify the plumbing works. Operational validation ensures the water that comes out won't poison your business. The difference becomes painfully clear around day 12 of live operations, when you realize the supplier's "24-hour free cancellation" actually means 24 hours before check-in in the hotel's local time—not booking time, not your agency's time zone. Your terms clearly state something else. Now you're eating cancellation fees because nobody mapped these definitions during integration.

Essential data fields that break agencies

Certain fields consistently cause operational chaos when poorly validated. Not the obvious ones like price or availability—those get tested. It's the supporting fields that seem minor until they compound into major problems.

Cancellation policy mapping Every supplier structures cancellation data differently. Some send structured JSON with penalty amounts and deadlines. Others embed everything in text strings. A few use coded references you need to decode.

1. 1
   Penalty calculation method (percentage vs fixed amount)
2. 2
   Deadline format (hours before arrival, specific dates, booking-relative)
3. 3
   Time zone application
4. 4
   Partial cancellation handling
5. 5
   Amendment vs cancellation rules

One agency discovered their supplier's "72H" cancellation code meant 72 hours before the start of the travel date for packages but 72 hours before each component for itemized bookings. They found out after eating $4,800 in unexpected penalties across a group booking.

Room and rate categorization "Standard Room" means wildly different things across suppliers. Your checklist needs mappings for:

1. 1
   Bed configurations (does "Double" mean one double bed or two singles?)
2. 2
   View descriptions (is "City View" the same as "Urban View"?)
3. 3
   Meal inclusions (does "BB" include hot breakfast or just continental?)
4. 4
   Occupancy rules (can a "Triple" room take 2 adults + 2 children?)

Create a matrix comparing your internal categories against each supplier's codes. Test weird edge cases—family rooms, connecting rooms, accessible rooms. These specialty categories often have completely different handling rules that standard room tests miss.

Commission and markup structures Commission calculation seems straightforward until you hit these scenarios:

1. 1
   Net rates with suggested retail vs commissionable rates
2. 2
   Tiered commission based on volume or booking value
3. 3
   Different commission for different components
4. 4
   FIT vs group commission variations
5. 5
   Seasonal commission adjustments

Map out exactly how each rate type flows through your pricing engine. A 2% calculation error on a $50,000 group booking hurts. Multiply that across hundreds of bookings and you're hemorrhaging margin.

Test cases that catch expensive surprises

Generic test bookings rarely surface real operational issues. You need test cases designed to break things in ways that mirror actual business complexity.

Multi-currency scenarios

1. 1
   Customer pays in USD
2. 2
   Supplier charges in EUR
3. 3
   Hotel operates in THB
4. 4
   Refunds process in a fourth currency

Watch for rounding errors, conversion timing differences, and which system's exchange rate takes precedence. One agency lost around $12,000 over six months from cumulative rounding differences they never noticed.

Date boundary testing

1. 1
   Cross daylight savings transitions
2. 2
   Span month boundaries
3. 3
   Include Feb 29 on leap years
4. 4
   Have check-in at 11

   59 PM

5. 5
   Cross international date lines

These edge cases reveal how different systems handle date math—especially critical for calculating cancellation deadlines and payment schedules.

Inventory limit testing

1. 1
   15 rooms when only 14 exist
2. 2
   A booking at maximum stay length
3. 3
   Inventory exactly at allocation boundaries
4. 4
   Back-to-back bookings for the same room

This surfaces how the API handles partial availability, waitlists, and allocation rules.

Component modification testing

1. 1
   Change just the flight while keeping the hotel
2. 2
   Modify passenger names after partial payment
3. 3
   Add insurance after booking confirmation
4. 4
   Cancel one room from a multi-room booking

Modification capabilities vary wildly between suppliers. Better to know the limitations before promising flexibility to clients.

Building reconciliation smoke tests

Reconciliation tests run continuously after integration to catch drift between what the API reports and operational reality. Think of them as ongoing monitoring, not one-time validation.

Daily rate parity checks

1. 1
   Your API integration
2. 2
   The supplier's agent portal
3. 3
   Their consumer website
4. 4
   Competitor sites using the same supplier

Flag any variations over 3%. Small differences compound into margin erosion and customer complaints about finding better prices elsewhere.

Availability sync verification

1. 1
   API availability matches supplier portal
2. 2
   Sold-out status syncs within 5 minutes
3. 3
   Allocation counts align
4. 4
   Waitlist positions update correctly

Every morning, select five random high-demand products and verify the items above. One agency found their API was showing availability 6 hours behind reality. They'd been confirming bookings all morning that were already sold out.

Booking status synchronization

1. 1
   Confirmation numbers match across systems
2. 2
   Passenger details transferred correctly
3. 3
   Special requests were communicated
4. 4
   Payment status aligns

For every tenth booking, manually verify the items above. Keep a simple spreadsheet tracking these checks. Patterns emerge quickly—maybe amendments never sync properly, or group bookings lose passenger details.

Commission calculation audit

1. 1
   Expected commission based on your agreement
2. 2
   What the API reported
3. 3
   What appeared in supplier statements
4. 4
   What hit your bank account

Weekly, randomly select 10 bookings and manually calculate the items above. Track variances in a simple table. Even 0.5% systematic underpayment adds up to thousands annually.

“

Automate daily parity checks to surface price variances before they impact customers.

Track variances in a simple table. Even 0.5% systematic underpayment adds up to thousands annually.

The mapping exercise everyone skips

Before any test booking, create three critical mapping documents. These become your operational reference for the life of the integration.

Status code dictionary

1. 1
   "CNF" = Confirmed (but does it mean payment received or just booking accepted?)
2. 2
   "HLD" = Holding (how long? what triggers release?)
3. 3
   "WTL" = Waitlisted (is position provided? how are confirmations handled?)

Include status transition rules. Can a "Pending" booking jump straight to "Cancelled" or must it pass through "Confirmed" first? These state machines drive your operational workflows.

Error code translator

1. 1
   "RATENOTAVAILABLE" = check if sold out or if rate plan expired
2. 2
   "INVALID_PASSENGER" = usually means name format, but sometimes age restrictions
3. 3
   "PAYMENT_FAILED" = could be a processing issue or could mean fraud flag

Add the operational response for each error. Who gets notified? What's the client communication? What's the resolution workflow?

Field format specifications Create a table showing how each system expects data:

This prevents the thousand small formatting issues that cause bookings to fail mysteriously.

Reconciliation schedules and thresholds

Set up recurring checks with clear action triggers. Don't just monitor—define what happens when things drift.

Daily reconciliation (every morning)

1. 1
   All confirmations received
2. 2
   Payment statuses align
3. 3
   No orphaned bookings
4. 4
   Commission tracked correctly

Threshold: Any single discrepancy triggers investigation. Three discrepancies in a week triggers supplier escalation.

Weekly deep-dive (Mondays)

1. 1
   Rate parity across 20 random samples
2. 2
   Availability accuracy for top 10 products
3. 3
   Average response times
4. 4
   Error rate trends

Threshold: >5% error rate or >3-second response degradation triggers technical review.

Monthly financial reconciliation

1. 1
   Total bookings count
2. 2
   Commission amounts
3. 3
   Refunds processed
4. 4
   Currency conversion rates applied

Threshold: >$100 or >1% variance triggers formal dispute process.

Avoiding the integration valley of death

Most agencies go through an "integration valley"—the period after technical connection but before operational stability. Bookings work but margin leaks everywhere. Customer complaints spike. Staff scrambles to handle edge cases.

The valley typically lasts 30-60 days if you catch it early. Six months if you don't. Some agencies never fully stabilize, accepting a permanent state of semi-broken integration.

Proper pre-validation prevents this by catching issues during controlled testing rather than live operations. But it requires discipline. The pressure to go live immediately after technical integration is real—sales wants to move the new inventory, marketing has campaigns queued, leadership sees competitors already offering these products.

Here's what actually unfolds in agencies that skip validation:

1. 1
   Week 1-2

   Excitement. New bookings flowing. Everyone celebrates the expanded inventory.

2. 2
   Week 3-4

   First cracks appear. A few bookings error out. Some rates look wrong. Support tickets increase but seem manageable.

3. 3
   Week 5-8

   Full crisis mode. Daily fires around failed bookings, wrong prices, availability mismatches. Staff morale tanks. Some customers demand refunds.

4. 4
   Week 9-12

   Attempted stabilization. Bandaid fixes everywhere. Manual processes to work around API issues. Margins compressed from eating mistakes.

5. 5
   Month 4-6

   Resignation or rebuild. Either accept the broken state or finally do the validation that should have happened at the start.

Proper pre-validation prevents this by catching issues during controlled testing rather than live operations. But it requires discipline.

Building validation into your operational workflow

The best agencies treat API validation as an ongoing operational discipline, not a one-time project. They build it into standard workflows using a mix of manual checks and automation tools.

Operational software can automatically flag when API response patterns change, alert on reconciliation discrepancies, and track validation metrics over time—shifting validation from a manual burden into a systematic process that runs in the background. That's where it gets genuinely useful. Not as a replacement for the initial mapping work, but as a way to catch drift that would otherwise go unnoticed for weeks.

A simple daily dashboard showing five key metrics beats a complex monthly report nobody reads. Automated alerts for threshold breaches beat manual checking that gets skipped when things get busy.

Some agencies integrate checks directly into their booking flow—automatically comparing API prices against manual portal checks for high-value bookings, or flagging bookings that return unfamiliar error codes for manual review. That kind of real-time layer catches issues before they become client problems.

Your validation investment pays for itself

Proper API validation feels like overhead until you calculate the true cost of integration failures. Take a typical agency running around 50 bookings per month:

1. 1
   2% of bookings with pricing errors = roughly 1 booking/month
2. 2
   Average pricing error = $200 in lost margin
3. 3
   5% requiring manual intervention = ~2-3 bookings × 1 hour each
4. 4
   1% resulting in customer complaints = reputation damage that's hard to quantify

That's $400+ in direct losses plus several hours of crisis management every month. Over a year, you're looking at $5,000 or more in direct costs, plus the hidden cost of staff burnout and customer churn.

Compare that to 20 hours upfront in proper validation and maybe 2 hours monthly in ongoing reconciliation. The math is obvious.

Beyond the economics, solid validation gives you operational confidence. You can sell new products knowing they'll actually work. Staff can focus on service instead of firefighting. You can scale inventory without scaling the chaos.

And you avoid the 2 AM calls from clients stranded because their "confirmed" booking doesn't exist in the hotel's system. Those moments—when operational failures become real customer disasters—are what erode agencies over time.

This checklist isn't about achieving a perfect integration. Some issues will still slip through. But the difference between catching 90-95% of problems versus 50% determines whether your agency thrives with expanded inventory or drowns trying to manage it.

Start with the basics: map your essential fields, run the core test cases, set up daily reconciliation. Build from there. The goal isn't perfection on day one—it's avoiding the compounding surprises that turn into operational nightmares. Your suppliers won't provide this level of validation guidance. They care about technical connectivity, not your operational reality. Your tech team may not fully understand the business implications of data mismatches. This work sits squarely in operations—where technical capabilities meet business requirements. That's exactly why it falls through the cracks so often, and why the agencies that take it seriously tend to outperform the ones that don't.