Best Practices — Buyer Integration

1. Initial Data Load (First Time Setup)

Hotels

• Fetch all hotels without any filter.
• But always use:
  • limit (100 or as agreed)
  • resumeKey
• Continue pagination until resumeKey = null.

Rooms

• Fetch all rooms without any filter.
• But always use:
  • limit (100 or as agreed)
  • resumeKey
• Complete full pagination.

2. Incremental Updates (After Initial Load)

Hotels

Use:

since: <lastTimestamp>

This returns:

• New properties
• Updated properties
• Disabled / deleted properties

Rooms

• When using since for hotels:
  • You may receive new propertyIds.
• Use those propertyIds to fetch corresponding room data:

GetPropertyRoomData(propertyIds: [...])

• Alternatively:
  • Use roomTypeIds for targeted updates.

3. Geo-Based Fetching (Optional)

If your account is enabled for geo hierarchy, you can fetch geo data and then hotels using:

Step 1

GetCountries – Fetch all countries.

Step 2

GetStates – Fetch all states based on country codes.

Step 3

GetCities – Fetch all cities based on country codes + state codes.

Step 4

GetHotels based on country, city, or state + country.

Filter	Example
countryCode	US
countryCode + stateCode	US + NY
city	cityId

Use this mainly for:

• Controlled onboarding
• Region-specific inventory

4. Webhook-Driven Updates

• You will receive webhooks containing:
  • propertyId
  • roomTypeId

Recommended Action

• Immediately fetch updated data using:
  • propertyId → Hotel + Rooms
  • roomTypeId → Specific room

Processing Strategy

Choose one:

• Real-time pull (recommended)
• Queue-based processing
  • Batch process updates

Important:

• Do not delay processing beyond 24 hours.

5. Pagination Strategy

Always use:

• limit → recommended: 100 (or as agreed)
• resumeKey → for next page

Why this matters

• Prevents data loss
• Ensures stable ingestion for large datasets

6. Static Data Refresh

The following do NOT send webhook updates:

• Countries
• States
• Cities
• Geo hierarchy
• Meal plans

Recommendation

• Refresh at least once per week.
• Or more frequently based on business needs.

7. Mapping & ID Management

Each property may include mappings based on your preferred mapping provider IDs, such as:

• Vervotech ID
• GIATA ID
• Your internal hotel ID

Travel buyers may choose to receive:

• A single mapping provider ID
• Multiple mapping provider IDs
• All available mapping provider IDs simultaneously

For example, buyers may request:

• Only GIATA IDs
• Only Vervotech IDs
• GIATA + Vervotech IDs
• Their own internal hotel IDs
• Any combination of the above

Please contact your Hotel Trader Technical Account Manager to specify your preferred mapping provider configuration.

If you are interested in receiving your own internal hotel IDs within the Merchandising API responses, please provide your complete inventory along with accurate and comprehensive metadata in the required file format.

Please note that data accuracy and completeness are essential for successful hotel mapping.

orbit_template_client_mapping.csv

Best Practices

• Map immediately when received.
• Sometimes this value can be null. You will get webhook updates when the mapping updates.

8. Critical Do’s & Don’ts

Do

• Use delta (since) after initial load.
• Process webhooks quickly.
• Use pagination always.
• Refresh static data periodically.
• Fetch rooms for new properties immediately.

Don’t

• Skip pagination (resumeKey).
• Run repeated full loads.
• Ignore webhook updates.
• Delay sync beyond 24 hours.

Integration Summary

Phase	Hotels	Rooms
Initial Load	No filter + pagination	No filter + pagination
Incremental	since	propertyIds / roomTypeIds
Webhooks	Use propertyId	Use propertyId or roomTypeId