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.

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