Best Practices — Buyer Integration

1. Initial Data Load (First Time Setup)

Hotels

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

Rooms

• Fetch all rooms without any filter.
• But always use:
  • limit (20 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 roomIds 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
  • roomId

Recommended Action

• When you receive a webhook, send a confirmation or HTTP 200 Message immediately and then fetch updated data using:
  • propertyId → Hotel + Rooms
  • roomId → Specific room
• It is not recommended to process and update the data first and then later send webhook receive confirmation
  • 
    

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: 20 (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 and process each webhook message.
• 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 immediately after sending an HTTP 200 confirmation Message
• 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 /roomId
Webhooks	Use propertyId	Use propertyId orroomID