Bookings¶
This resource represents a container for a collection of booked services on various products, the sum of which make up a travel itinerary. It is the core object which links objects such as payment & refund transactions, invoice & voucher travel documents, and services with travellers.
XML Schema:
GET: Get a Booking
POST: Create a Booking
PATCH: Update a Booking
Fields
Name |
Type |
Description |
|---|---|---|
id read-only |
String |
|
href read-only |
Field |
|
date_of_first_travel read-only |
Date |
|
date_of_last_travel read-only |
Date |
|
external_id |
String |
An identifier to this resource provided by and for an external system. Uniqueness is not enforced. |
currency required |
String |
The currency ISO code for the booking, in the standard Currencies & Prices. All price or cost fields for the booking resource, or associated service, payment, and refund resources, are in this currency. |
date_created read-only |
Datetime |
The time when the resource was created, in the standard Dates & Times. |
date_closed read-only |
Date |
The date this booking was closed and no further changes can be made, in the standard Dates & Times. |
balance_due_date read-only |
Date |
The latest date the amount owing for this booking must be paid to G Adventures, in the standard Dates & Times. |
amount_paid read-only |
Decimal |
The currency-specific total amount that has already been paid on this booking to G Adventures, in the standard Currencies & Prices. |
amount_owing read-only |
Decimal |
The currency-specific total amount still owing on this booking to G Adventures, The currency ISO code, in the standard Currencies & Prices. |
amount_pending read-only |
Decimal |
The currency-specific pending amount, an amount referencing total pending payments subtracted by pending refunds. |
commission read-only |
Decimal |
The currency-specific commission amount (sum of all service commission amounts) that the booking agent will receive for this booking, in the standard Currencies & Prices. |
tax_on_commission read-only |
Decimal |
The tax on the commission paid to the booking agent, in the standard Currencies & Prices. This is applicable to some Canadian agents. For the latest guidelines, please consult the Canada Revenue Agency. This also applies to UK agents under the G Adventures ATOL agreement. |
linked_bookings |
Field |
A list of bookings that are linked together with this one. |
|
String |
|
|
Field |
|
|
Date |
|
|
Date |
|
booking_company read-only |
Reference Object |
The booking_company associated with this booking. |
agent read-only |
Reference Object |
|
agency read-only |
Reference Object |
|
associated_agency read-only |
Reference Object |
The agency that has some type of relationship with this booking’s agency. |
agency_identifier |
Nested Object |
Used at booking creation to identify the agency to assign to the new booking. |
|
String |
The field used to identify the agency. Possible values:
* |
|
String |
The value of the given field. |
agency_chain read-only |
Reference Object |
The agency chain associated with this booking |
services read-only |
Nested Object |
|
invoices read-only |
Nested Object |
|
payments read-only |
Nested Object |
|
checkins read-only |
Nested Object |
A list of checkins associated with the booking. |
requirements read-only |
Nested Object |
A list of requirements associated with the booking. |
refunds read-only |
Nested Object |
|
documents read-only |
Nested Object |
|
overrides read-only |
Nested Object |
|
customers read-only |
Nested Object |
|
travel_credits read-only |
Nested Object |
A list of travel_credit applied to the booking. |
payment_links read-only |
Nested Object |
A list of payment links associated with the booking. |
Get a Booking¶
- GET /bookings/(string: booking_id)¶
Request
curl -H "X-Application-Key: YOUR_APPLICATION_KEY"
https://rest.gadventures.com/bookings/489854
Response
{
"id": "489854",
"href": "https://rest.gadventures.com/bookings/489854",
"date_of_first_travel": "2012-01-13",
"date_of_last_travel": "2012-02-04",
"external_id": null,
"currency": "CAD",
"date_created": "2011-11-11T11:33:02Z",
"date_closed": "2012-03-05",
"balance_due_date": "2011-11-16",
"amount_paid": "2496.17",
"amount_owing": "0.00",
"amount_pending": "0.00",
"commission": "0.00",
"tax_on_commission": "0.00",
"linked_bookings": [
{
"id": "488643",
"href": "https://rest.gadventures.com/bookings/488643"
},
{
"id": "489452",
"href": "https://rest.gadventures.com/bookings/489452"
}
],
"booking_company": {
"id": "1",
"href": "https://rest.gadventures.com/booking_companies/1"
},
"agent": {
"id": "49330",
"href": "https://rest.gadventures.com/agents/49330"
},
"agency": {
"id": "17884",
"href": "https://rest.gadventures.com/agencies/17884"
},
"associated_agency": null,
"agency_chain": {
"id": "a7P14000000TWPAEA4",
"href": "https://rest.gadventures.com/agency_chains/a7P14000000TWPAEA4"
},
"services": {
"href": "https://rest.gadventures.com/bookings/489854/services"
},
"invoices": {
"href": "https://rest.gadventures.com/bookings/489854/invoices"
},
"payments": {
"href": "https://rest.gadventures.com/bookings/489854/payments"
},
"checkins": {
"href": "https://rest.gadventures.com/bookings/489854/checkins"
},
"requirements": {
"href": "https://rest.gadventures.com/bookings/489854/requirements"
},
"refunds": {
"href": "https://rest.gadventures.com/bookings/489854/refunds"
},
"documents": {
"href": "https://rest.gadventures.com/bookings/489854/documents"
},
"overrides": {
"href": "https://rest.gadventures.com/bookings/489854/overrides"
},
"customers": {
"href": "https://rest.gadventures.com/bookings/489854/customers"
},
"travel_credits": {
"href": "https://rest.gadventures.com/bookings/489854/travel_credits"
},
"payment_links": {
"href": "https://rest.gadventures.com/bookings/489854/payment_links"
}
}List Customer Bookings
Each booking is represented as a separate resource and must be fetched
using the href value.
- GET /customers/(string: customer_id)/bookings¶
Request
curl -H "X-Application-Key: YOUR_APPLICATION_KEY"
https://rest.gadventures.com/customers/719923/bookings
Response
{
"count": 83,
"max_per_page": 50,
"current_page": 1,
"links": [
{
"href": "https://rest.gadventures.com/customers/719923/bookings?max_per_page=50&page=2",
"rel": "next"
}
],
"results": [
{
"id": "1494507",
"href": "https://rest.gadventures.com/bookings/1494507",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "1456927",
"href": "https://rest.gadventures.com/bookings/1456927",
"date_of_first_travel": "2019-08-10",
"date_of_last_travel": "2019-08-21"
},
{
"id": "1385114",
"href": "https://rest.gadventures.com/bookings/1385114",
"date_of_first_travel": "2019-02-24",
"date_of_last_travel": "2019-03-03"
},
{
"id": "1376209",
"href": "https://rest.gadventures.com/bookings/1376209",
"date_of_first_travel": "2019-04-04",
"date_of_last_travel": "2019-04-20"
},
{
"id": "1375257",
"href": "https://rest.gadventures.com/bookings/1375257",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "1351396",
"href": "https://rest.gadventures.com/bookings/1351396",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "1315686",
"href": "https://rest.gadventures.com/bookings/1315686",
"date_of_first_travel": "2018-09-19",
"date_of_last_travel": "2018-09-24"
},
{
"id": "1282569",
"href": "https://rest.gadventures.com/bookings/1282569",
"date_of_first_travel": "2018-07-16",
"date_of_last_travel": "2018-07-23"
},
{
"id": "1274979",
"href": "https://rest.gadventures.com/bookings/1274979",
"date_of_first_travel": "2018-06-14",
"date_of_last_travel": "2018-06-22"
},
{
"id": "1222795",
"href": "https://rest.gadventures.com/bookings/1222795",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "1199385",
"href": "https://rest.gadventures.com/bookings/1199385",
"date_of_first_travel": "2018-02-20",
"date_of_last_travel": "2018-02-23"
},
{
"id": "1197534",
"href": "https://rest.gadventures.com/bookings/1197534",
"date_of_first_travel": "2018-02-28",
"date_of_last_travel": "2018-03-02"
},
{
"id": "1193172",
"href": "https://rest.gadventures.com/bookings/1193172",
"date_of_first_travel": "2018-02-19",
"date_of_last_travel": "2018-03-06"
},
{
"id": "1162217",
"href": "https://rest.gadventures.com/bookings/1162217",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "1139267",
"href": "https://rest.gadventures.com/bookings/1139267",
"date_of_first_travel": "2017-09-20",
"date_of_last_travel": "2017-09-25"
},
{
"id": "1104447",
"href": "https://rest.gadventures.com/bookings/1104447",
"date_of_first_travel": "2017-08-19",
"date_of_last_travel": "2017-08-29"
},
{
"id": "1090963",
"href": "https://rest.gadventures.com/bookings/1090963",
"date_of_first_travel": "2017-10-27",
"date_of_last_travel": "2017-11-05"
},
{
"id": "1071171",
"href": "https://rest.gadventures.com/bookings/1071171",
"date_of_first_travel": "2017-04-23",
"date_of_last_travel": "2017-04-30"
},
{
"id": "1002029",
"href": "https://rest.gadventures.com/bookings/1002029",
"date_of_first_travel": "2016-11-01",
"date_of_last_travel": "2016-11-12"
},
{
"id": "985110",
"href": "https://rest.gadventures.com/bookings/985110",
"date_of_first_travel": "2016-09-21",
"date_of_last_travel": "2016-09-28"
},
{
"id": "948563",
"href": "https://rest.gadventures.com/bookings/948563",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "948559",
"href": "https://rest.gadventures.com/bookings/948559",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "926151",
"href": "https://rest.gadventures.com/bookings/926151",
"date_of_first_travel": "2016-04-08",
"date_of_last_travel": "2016-04-16"
},
{
"id": "905527",
"href": "https://rest.gadventures.com/bookings/905527",
"date_of_first_travel": "2016-02-17",
"date_of_last_travel": "2016-02-21"
},
{
"id": "905049",
"href": "https://rest.gadventures.com/bookings/905049",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "888213",
"href": "https://rest.gadventures.com/bookings/888213",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "888209",
"href": "https://rest.gadventures.com/bookings/888209",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "888144",
"href": "https://rest.gadventures.com/bookings/888144",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "887552",
"href": "https://rest.gadventures.com/bookings/887552",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "872499",
"href": "https://rest.gadventures.com/bookings/872499",
"date_of_first_travel": "2015-10-31",
"date_of_last_travel": "2015-11-13"
},
{
"id": "861311",
"href": "https://rest.gadventures.com/bookings/861311",
"date_of_first_travel": "2015-11-27",
"date_of_last_travel": "2015-12-06"
},
{
"id": "857122",
"href": "https://rest.gadventures.com/bookings/857122",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "844179",
"href": "https://rest.gadventures.com/bookings/844179",
"date_of_first_travel": "2015-10-10",
"date_of_last_travel": "2015-10-14"
},
{
"id": "828281",
"href": "https://rest.gadventures.com/bookings/828281",
"date_of_first_travel": "2015-06-09",
"date_of_last_travel": "2015-06-09"
},
{
"id": "815673",
"href": "https://rest.gadventures.com/bookings/815673",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "815672",
"href": "https://rest.gadventures.com/bookings/815672",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "808681",
"href": "https://rest.gadventures.com/bookings/808681",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "808667",
"href": "https://rest.gadventures.com/bookings/808667",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "808295",
"href": "https://rest.gadventures.com/bookings/808295",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "808288",
"href": "https://rest.gadventures.com/bookings/808288",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "808283",
"href": "https://rest.gadventures.com/bookings/808283",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "808280",
"href": "https://rest.gadventures.com/bookings/808280",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "804102",
"href": "https://rest.gadventures.com/bookings/804102",
"date_of_first_travel": "2015-04-16",
"date_of_last_travel": "2015-04-20"
},
{
"id": "796109",
"href": "https://rest.gadventures.com/bookings/796109",
"date_of_first_travel": "2015-04-20",
"date_of_last_travel": "2015-04-23"
},
{
"id": "783296",
"href": "https://rest.gadventures.com/bookings/783296",
"date_of_first_travel": "2015-04-14",
"date_of_last_travel": "2015-04-24"
},
{
"id": "779937",
"href": "https://rest.gadventures.com/bookings/779937",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "778524",
"href": "https://rest.gadventures.com/bookings/778524",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "753389",
"href": "https://rest.gadventures.com/bookings/753389",
"date_of_first_travel": null,
"date_of_last_travel": null
},
{
"id": "737239",
"href": "https://rest.gadventures.com/bookings/737239",
"date_of_first_travel": "2014-11-02",
"date_of_last_travel": "2014-11-20"
},
{
"id": "649035",
"href": "https://rest.gadventures.com/bookings/649035",
"date_of_first_travel": "2013-12-11",
"date_of_last_travel": "2013-12-23"
}
]
}Create a Booking¶
Bookings are created by making HTTP POST request to /bookings/ resource.
Example request:
POST /bookings/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type:application/json
{
"currency": "CAD",
"external_id": "FUN1"
}
Example response:
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "628360",
"href": "/bookings/628360/"
"external_id": "FUN1",
"currency": "CAD",
"date_created": "2013-09-13T17:18:06Z",
"date_closed": null,
"date_of_first_travel": "2013-09-13",
"date_of_last_travel": "2013-09-13",
"balance_due_date": "2013-09-13",
"amount_paid": "0.00",
"amount_owing": "0.00",
"commission": "0.00",
"tax_on_commission": "0.00",
"agent": {
"id": "49284",
"href": "/agents/49284"
},
"services": {
"href": "/bookings/628360/services"
},
"invoices": {
"href": "/bookings/628360/invoices"
},
"payments": {
"href": "/bookings/628360/payments"
},
"refunds": {
"href": "/bookings/628360/refunds"
}
}
Create a Customer
Example request:
POST /customers/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type:application/json
{
"name": {
"legal_first_name": "Thievery",
"legal_last_name": "Corp",
"title": "Mr"
},
"date_of_birth": "1980-10-05",
"medical_notes": "perfect",
"account_email": "thievery.corp@gadventures.com"
}
Example response:
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "1323083",
"href": "/customers/1323083",
"name": {
"legal_first_name": "Thievery",
"legal_last_name": "Corp",
"legal_middle_name": null,
"common_name": null,
"title": "Mr"
},
"date_of_birth": "1980-10-05",
"place_of_birth": null,
"nationality": null,
"passport": {
"number": null,
"issue_date": null,
"expiry_date": null,
"place_of_issue": null
},
"medical_notes": "perfect",
"meal_preference": null,
"meal_notes": null,
"account_email": "thievery.corp@gadventures.com",
"phone_numbers": null,
"emergency_contacts": {
"first_name": null,
"last_name": null,
"phone_numbers": null
},
"address": {
"street": null,
"city": null,
"state": null,
"country": null,
"postal_zip": null,
"latitude": null,
"longitude": null
},
"bookings": {
"href": "/customers/1323083/bookings"
}
}
Create a Departure Service
Example request:
POST /departure_services/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type:application/json
{
"booking": {
"id": "628360"
},
"product": {
"id": "420482"
},
"customers": [
{
"id": "1323083"
}
]
}
Example response:
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"id": "1162343",
"href": "/departure_services/1162343",
"name": "Indochina Discovery",
"status": "Option",
"status_transitions": ["Expired"],
"type": "departure_services",
"sub_type": "Tour",
"start_date": "2013-12-07",
"finish_date": "2014-01-05",
"customers": {
"id": "1323083",
"href": "/customers/1323083",
"name": {
"legal_first_name": "Thievery",
"legal_last_name": "Corp",
"legal_middle_name": null,
"common_name": null,
"title": "Mr"
},
},
"date_created": "2013-09-13T18:42:47Z",
"date_confirmed": null,
"date_cancelled": null,
"option_expiry_date": "2013-09-17T18:42:46Z",
"purchase_price": "2549.00",
"commission": "0.00",
"applied_promotion": {
"id": "25358",
"name": "Promo for CAD",
"promotion_code": "PFCAD",
"discount_amount": "100.00",
"commission_rate": null,
"terms_and_conditions": null
},
"flags": [],
"booking": {
"id": "628360",
"href": "/bookings/628360"
},
"documents": null,
"product": {
"id": "420482",
"href": "/departures/420482",
"name": "Indochina Discovery"
},
"rooms": {
"code": "STANDARD",
"name": "Standard",
"customer": null
},
"incomplete_requirements": [
{
"type": "CONFIRMATION",
"name": "Nationality",
"code": "NATIONALITY",
"message": "Nationality must be submitted for this product. 'nationality' must be set in the customer resource.",
"customer": {
"id": "1323083",
"href": "/customers/1323083",
"name": {
"legal_first_name": "Thievery",
"legal_last_name": "Corp",
"legal_middle_name": null,
"common_name": null,
"title": "Mr"
},
}
},
{
"type": "CHECKIN",
"name": "Passport Number",
"code": "PASSPORT_NUMBER",
"message": "Passport number must be submitted for this product. The 'number' field (in the 'passport' data) must be set in the customer resource.",
"customer": {
"id": "1323083",
"href": "/customers/1323083",
"name": {
"legal_first_name": "Thievery",
"legal_last_name": "Corp",
"legal_middle_name": null,
"common_name": null,
"title": "Mr"
},
}
}
],
"arrival_flight_details": [],
"departure_flight_details": [],
"international_ticket_numbers": [],
"traveller_heights": []
}
Update a Booking¶
- PATCH /bookings/(string: booking_id)/¶
Example request:
PATCH /bookings/628168/ HTTP/1.1
Host: rest.gadventures.com
Accept: application/json
Content-Type: application/json
{
"external_id": "Arctic August"
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "628168",
"href": "/bookings/628168",
"external_id": "Arctic August",
"currency": "CAD",
"date_created": "2013-08-26T19:53:10Z",
"date_closed": null,
"date_of_first_travel": "2013-11-10",
"date_of_last_travel": "2013-11-24",
"balance_due_date": "2013-09-11",
"amount_paid": "0.00",
"amount_owing": "0.00",
"commission": "0.00",
"tax_on_commission": "0.00",
"agent": {
"id": "70958",
"href": "/agents/70958"
},
"services": {
"href": "/bookings/628168/services"
},
"invoices": {
"href": "/bookings/628168/invoices"
},
"payments": {
"href": "/bookings/628168/payments"
},
"refunds": {
"href": "/bookings/628168/refunds"
}
}