Introduction

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 services, 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 services 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.
id read-only	String
href read-only	Field
date_of_first_travel read-only	Date
date_of_last_travel read-only	Date
booking_company read-only	Reference Object	The booking_company associated with this booking.
agent read-only	Reference Object	The agent associated with this booking.
agency read-only	Reference Object	The agencies with this booking
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.
field required	String	The field used to identify the agency. Possible values: * `id` - the primary Identifer for an agency resource * `transactional_email` - the transactional email field on the agency resource
value required	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	A list of services associated with the booking.
invoices read-only	Nested Object	A list of invoices associated with the booking.
payments read-only	Nested Object	A list of payments associated with the booking.
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	A list of refunds associated with the booking.
documents read-only	Nested Object	A list of documents associated with the booking.
overrides read-only	Nested Object	A list of overrides associated with the booking.
customers read-only	Nested Object	A list of customers associated with the booking.
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)¶

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¶

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"
    }
}