OrderPoll Endpoint: Efficient Order Retrieval and Synchronization

The /OrderPoll endpoint provides an efficient way to retrieve and synchronize orders from the AirGateway API. This endpoint is designed to replace the deprecated /OrderList endpoint and offers improved performance through advanced filtering, pagination, and cursor-based retrieval.

This approach not only simplifies the process of order synchronization for developers and businesses but also ensures that integrations have access to real-time order updates through a unified interface.

Parameters

The /OrderPoll endpoint accepts the following optional parameters:

• nextCursor (String) - When omitted, returns orders from the last month. When provided, returns orders that were modified since the previous request. It also saves the filters from the first request, meaning filters are not needed on subsequent requests.
Example:

# First request with filter
GET /OrderPoll?subagencyName=MyTravelAgency

# Response includes nextCursor
{
  "nextCursor": "MDI0NDA3MzU3MQ==",
  "orders": [...]
}

# Subsequent request - filter automatically applied
GET /OrderPoll?nextCursor=MDI0NDA3MzU3MQ==
# This will automatically include subagencyName=MyTravelAgency filter

• subagencyName (String) - Filter orders by specific subagency name.

• providers (String) - Filter by providers. Multiple providers separated by commas (e.g., “BA,FR”).

Response Structure

The response includes the following fields:

• nextCursor - Cursor value for retrieving newer orders in subsequent requests, using the same filters used in the first request

• orders - Array of order objects containing id, pnr, createdAt (Unix timestamp), modifiedAt (Unix timestamp), and subagencyName

Orders are returned sorted by their modification timestamp (modifiedAt) in ascending order (oldest to newest).

Usage Examples

Basic Request (Last Month’s Orders):

GET /OrderPoll

Next cursor request, using the same filters used in the first request:

GET /OrderPoll?nextCursor=MDI0NDA3MzU3MQ==

Filtered Request by Subagency:

GET /OrderPoll?subagencyName=MyTravelAgency

Filtered Request by Providers:

GET /OrderPoll?providers=BA,FR

Error Handling

Our API handles errors as follows:

• HTTP 422 Bad Request - Returned when the nextCursor parameter is in an invalid format.

• HTTP 404 Not Found - Returned when the subagencyName does not exist.

• HTTP 200 OK - Successful request with results. When no orders match the criteria, the response contains an empty orders array.

• HTTP 540 Platform Maintenance - When the AirGateway platform is undergoing maintenance, the API returns this specific error code.

Key Features

Cursor-Based updates: Uses nextCursor parameter for efficiently fetching updates and eliminates the need to fetch all orders repeatedly.

Advanced Filtering: Filter by subagency name and specific providers, with the ability to combine multiple filters for precise results.

Efficient Synchronization: Retrieve only new or modified orders since last poll, reducing data transfer and processing overhead.

Migration from OrderList

Important Deprecation Notice: The /OrderList endpoint will be fully decommissioned in Sept 2025. All integrations must migrate to /OrderPoll before this date.

To migrate from OrderList:

1. Update API calls to use /OrderPoll instead of /OrderList
2. Implement cursor-based fetching updates logic in your integration
3. Update response parsing to handle the new response structure
4. Test thoroughly to ensure compatibility
5. Monitor performance improvements

The new endpoint provides better efficiency, advanced filtering capabilities, and improved real-time synchronization compared to the legacy OrderList endpoint.