Reconciliation Reports API v2.1

The Reconciliation Reports API lets you see the status, validate, and upload your Commissions reconciliation reports. This only applies if you are in the Google Hotal Ads Commissions Program (GHACP).

For information about working with reconciliation reports in the Hotel Ads Center, see Reconciliation reports.

Paths

GET base_path/api_version/account_id/reconciliation_reports
GET base_path/api_version/account_id/reconciliation_reports/date_time/file_name
POST base_path/api_version/account_id/reconciliation_reports
POST base_path/api_version/account_id/reconciliation_reports/validate

Where:

Path Parameter Description
base_path https://www.googleapis.com/travelpartner
api_version v2.1
account_id A parent account or sub account ID.
date_time Specifies the datetime that a report was previously uploaded. Use this parameter with the file_name to uniquely identify a report to download.

This parameter uses the ISO 8601 date format. For example, "2016-06-01T14%3A11%3A00" ("%3A" replaces ":" in the URL-encoded value).

file_name Specifies the name of the reconciliation report to download. This parameter, in combination with the date_time, uniquely identifies the report.
validate Validates the attached report in a POST request.

Query String Parameters

Parameter Description
end_date_time (Optional) Specifies the end of a date range when getting a list of reports. The beginning of the date range is defined by the start_date_time query string parameter.

When defining a range for a month's reports, use the last day of the month for which you want the report.

This parameter uses the ISO 8601 date format. For example, "2016-06-30T11%3A59%3A59". In this example, "%3A" replaces ":" in the URL-encoded value.

This value uses America/Los Angeles time.

start_date_time (Optional) Specifies the datetime from which the API returns a list of available reports. If you also specify the end_date_time query string parameter, then start_date_time defines the beginning of the range for which you want to get a list of reports.

When defining a range for a month's reports, use the first day of the month for which you want the report.

This parameter uses the ISO 8601 date format. For example, "2016-06-01T14%3A11%3A00". In this example, "%3A" replaces ":" in the URL-encoded value.

This value uses America/Los Angeles time.

Supported Methods

HTTP Method Description
GET Gets a list of reconciliation reports that are available between the specified dates. Also, gets a specific report.
POST Validates a reconciliation report or uploads a report to Google.

Examples

Gets a list of recent reconciliation reports for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports

Gets a list of reconciliation reports that have been submitted since midnight on June 7, 2016 for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports?start_date_time=2016-06-01T12%3A00%3A00

Gets a list of reconciliation reports that were submitted between midnight on June 7, 2016 and midnight on September 7, 2016 for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports?start_date_time=2016-06-01T12%3A00%3A00&end_date_time=2016-09-31T12%3A00%3A00

Downloads the August 1, 2016 reconciliation report (named recon-report.csv) for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports/2016-08-01T12%3A00%3A00/recon-report.csv

Validates a reconciliation report that is included in the body of the request for account 4200042:

POST https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports/validate

Uploads a reconciliation report that is included in the body of the request for account 4200042:

POST https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports

Getting a list of reconciliation reports

You can use the Reconciliation Reports API to get a list of reconciliation reports that you can then download.

To get a list of recent reconciliation reports, send a GET request with the following syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_id/reconciliation_reports

The following example gets a list of reports for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports

The Reconciliation Reports API responds with a list of reports, their upload dates, and their names. In addition, the API indidates whether a report has been processed by Google.

The following sample response shows three reports that can be downloaded:

{
  "results": [
    {
      "resource_id": {
        "date_time": "2016-06-07T12:34:00",
        "file_name": "bookings.csv"
      },
      "processed": true
    },
    {
      "resource_id": {
        "date_time": "2016-07-07T12:34:00",
        "file_name": "bookings.csv"
      },
      "processed": true
    },
    {
      "resource_id": {
        "date_time": "2016-08-07T14:11:00",
        "file_name": "bookings.csv"
      },
      "processed": false
    }
  ]
}

In this example, the first two reports have been processed (processed = true). The third report has not yet been processed (processed = false).

The combination of the values of date_time and file_name uniquely identifies each report. You use these values in the URL path when downloading a report.

You can optionally specify the start date with the start_date_time query string parameter. This lets you get a list only of reports that were submitted since that date using following syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_id/reconciliation_reports/?start_date_time=datetime

The following example gets a list of available reconciliation reports since midnight on June 7, 2016 for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports?start_date_time=2016-06-01T12%3A00%3A00

In addition, you can also specify an end date by using the end_date_time query string parameter. This creates a date range for which you get a list of available reports.

The following example gets a list of reports between June 7, 2016 and September 7, 2016 for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports?start_date_time=2016-06-01T12%3A00%3A00&end_date_time=2016-09-30T12%3A00%3A00

Note that the "%3A" replaces a colon (":") in the URL-encoded format.

Downloading a reconciliation report

You can use the Reconciliation Reports API to download reports that you have previously uploaded to Google.

To download a report, send a GET request with the following URL syntax:

GET https://www.googleapis.com/travelpartner/v2.1/account_id/reconciliation_reports/date_time/file_name

The following example downloads the bookings.csv report that was uploaded at 2016-06-07T12:34:00 for account 4200042:

GET https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports/2016-06-07T12%3A34%3A00/bookings.csv

You can get the values to use for date_time and file_name by executing a GET request as described in Getting a list of reconciliation reports.

Validating a reconciliation report

You can use the Reconciliation Reports API to validate your reconciliation report before you upload it.

The reconciliation report is included in the body of the request, as the value for the contents field. The reconciliation report must follow the syntax described in Reconciliation reports.

To validate a report, send a POST request with the following URL syntax:

POST https://www.googleapis.com/travelpartner/v2.1/account_id/reconciliation_reports/validate

The following example validates a report for account 4200042:

POST https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports/validate

When sending a new report for validation, use the following rules:

  • The contents of the report must be the value of the contents field in the body of the request.
  • Optionally set the name of the report with the file_name field in the body of the request.
  • The first line must be the names of each of the report's columns.
  • Do not exceed 10MB.
  • Surround strings with double quotes and escape them in the data.
  • Set the Content-Type HTTP header to "application/json".

The following example shows the body of the request, with the report data set to the value of the contents field and the optional file_name field set:

{"contents": "Hotel ID,Hotel Name,Hotel Address,Hotel City,Hotel State/Region,Hotel PostalCode,Hotel Country Code,Hotel Phone Number,Booking Reference,Booking Date and Time,Check-in Date,Check-out Date,Number of Rooms,Number of Guests,Booking Revenue,Booking Revenue Currency,Booking Revenue Currency to Billing Currency Conversion Rate,Booking Status,Commission,Commission Currency,Commission Currency to Billing Currency Conversion Rate,Payment Date,Payment Status\n
111,\"Capybara Hotel and Spa\",123 Foo Driveway,Boston,MA,02472,US,+11234567890,2thHRTY,2016-01-04T12:12:12z,2016-02-01,2016-02-03,1,4,213.88,USD,1,Stayed,21.39,USD,1.0,2016-06-07,Paid
211,\"Mabel's Gabels\",45678 Bar Street,London,,KT13 0PU,GB,+440203456123,z452121A,2016-02-04T12:12:12z,2016-02-01,2016-02-03,1,3,414.21,GBP,1.57,Stayed,64.43,USD,1.0,2016-06-07,Paid
311,\"No-Tell Motels\",66 Acacia Avenue,Geneva,,1211,CH,+412241820000,42,2016-03-04T12:12:12z,2016-02-01,2016-02-03,1,2,451.15,CHF,1.05,Stayed,37.41,EUR,0.99889,2016-06-07,Paid",
"file_name": "2016-feb-report.csv"}

The report uses the CSV syntax described in Reconciliation reports.

After you submit a request for validation, the Reconciliation Reports API sends a response that indicates how many records (or lines in the report) are valid according to the expected CSV file syntax.

The following sample response shows that the 112-line report that was sent for validation passed the validation process:

{
  num_records_successful: 112
}

Validating a report does not upload it. To upload the report, use the instructions in Uploading a reconciliation report.

If one or more records fails validation, the Reconciliation Reports API responds with details about the failures.

The following sample response shows that two lines in the report failed validation:

issues: [
  {
    line_num: 42,
    description: "Row must contain 28 fields"
  },
  {
    line_num: 99,
    description: "Failed to parse Hotel Country Code"
  }
]

Correct any errors in the report and resubmit it for validation. After you have verified that the report is valid, you can upload the report using the instructions in Uploading your reconciliation report.

If you attempt to validate a reconciliation report that is identical (byte for byte) to an existing report, the Reconciliation Reports API returns a "304 (Not Modified)" and an empty response.

Uploading a reconciliation report

After you have confirmed that a reconciliation report is valid, you can upload it to Google using the Reconciliation Reports API.

To upload a reconciliation report, send a POST request with the following URL syntax:

POST https://www.googleapis.com/travelpartner/v2.1/account_id/reconciliation_reports

The following example uploads a report for account 4200042:

POST https://www.googleapis.com/travelpartner/v2.1/4200042/reconciliation_reports

When uploading a report, use the same rules and structure that are described in Validating a reconciliation report.

During the upload process, the Reconciliation Reports API validates the report and responds with a the same kind of response as a validate request.

If the upload fails, correct any errors in the report and upload the entire message again.

If you attempt to upload a reconciliation report that is identical (byte for byte) to an existing report, the Reconciliation Reports API returns a "304 (Not Modified)" and an empty response.

Reconciliation Reports API Changes

Changes to version 2.1 of the Reconciliation API include the following:

  • The API endpoint has changed from base_path/2.1/... to base_path/v2.1/...

Send feedback about...

Need help? Visit our support page.