Bookings

A Booking object represents a customer's reservation with you. It consolidates customer payments and related details into one entity.

Booking Model

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the booking.

  • Name
    gross_amount
    Type
    integer
    Description

    The total value of the booking (in pence).

  • Name
    currency
    Type
    string
    Description

    The currency of the booking. See the currency documentation.

  • Name
    email
    Type
    string
    Description

    The email address of the customer.

  • Name
    atol_receipt_number
    Type
    string
    Description

    The ATOL receipt number for the booking.

  • Name
    user
    Type
    object
    Description

    The user (object) that created the booking.

  • Name
    components
    Type
    array
    Description

    An array of booking component objects attached to the booking.

  • Name
    transactions
    Type
    array
    Description

    An array containing compact versions of the transaction model linked to the booking.

  • Name
    payment_links
    Type
    array
    Description

    An array containing compact versions of the payment link model associated with the booking.

  • Name
    customer_name
    Type
    string
    Description

    The name of the customer for whom the booking is made.

  • Name
    scheduled_transactions
    Type
    array
    Description

    An array containing scheduled payment models associated with the booking.

  • Name
    booking_reference
    Type
    string
    Description

    Your unique reference for the customer's booking.

  • Name
    departure_date
    Type
    date
    Description

    The date when the booking commences.

  • Name
    return_date
    Type
    date
    Description

    The date when the booking ends.

  • Name
    package_type
    Type
    object
    Description

    The package type of the booking.

  • Name
    created_at
    Type
    datetime
    Description

    The datetime when the booking was created in our systems.

  • Name
    updated_at
    Type
    datetime
    Description

    The datetime when the booking was last updated in our systems.

{
  "id": "226009ab-ffe9-4c80-922b-982e8e7849f8",
  "gross_amount": 1000000,
  "currency": "GBX",
  "email": "james.dean@gmail.com",
  "atol_receipt_number": "233234234",
  "user": {
    "id": "e8c243ff-d000-4f81-ba57-94184d44dae2",
    "email": "tom@felloh.com"
  },
  "components": [
    {
      "id": "8224bb6e-7d70-588b-82b8-316f2d71012e",
      "supplier": {
        "id": "6ab41ce7-36c8-5835-b997-492adb3d66e1",
        "name": "Felloh Travel - Packages",
        "created_at": "2022-06-28T17:27:59.616Z"
      },
      "amount": 56300,
      "currency": "GBX",
      "booking_reference": "X1232JJ",
      "destination_air": "AMS",
      "type": "packages",
      "created_at": "2023-02-15T16:00:18.886Z"
    }
  ],
  "transactions": [
    {
      "id": "fe9afbbf-0854-48af-acec-1efd1bed229a",
      "amount": 56300,
      "status": "COMPLETE",
      "method": "ONLINE",
      "type": "CARD",
      "created_at": "2022-01-28T10:58:31.165Z",
      "completed_at": "2022-01-28T10:58:31.165Z"
    }
  ],
  "payment_links": [
    {
      "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
      "amount": 1000,
      "description": "Deposit for Bali",
      "expires_at": "2021-12-17T15:10:37.589Z",
      "created_at": "2021-11-17T15:10:37.589Z",
      "email": "tom@felloh.com",
      "currency": "GBX",
      "methods": {
        "open_banking": true,
        "card": true
      }
    }
  ],
  "package_type": {
    "id": "AGENT_OF_ATOL_HOLDER",
    "created_at": "2023-04-04T09:41:12.021Z"
  },
  "scheduled_transactions": [
    {
        "id": "c5ee58d8-2141-4146-ac4c-2e689b97375f",
        "amount": 50,
        "currency": "GBX",
        "status": {
            "id": "COMPLETE"
        },
        "transaction": {
            "id": "c5ee58d8-2141-4146-ac4c-2e689b97375f",
            "amount": 50,
            "provider_reference": "",
            "currency": "GBX",
            "ip_address": "",
            "fingerprint": "",
            "ai_analysed": false
        },
        "execute_after": "2024-10-16T13:53:14.067Z",
        "completed_at": "2024-10-16T13:53:16.223Z",
        "created_at": "2024-10-16T13:53:14.075Z",
        "updated_at": "2024-10-16T13:53:14.075Z"
    }
  ],
  "customer_name": "James Dean",
  "booking_reference": "XXX123789",
  "departure_date": "2022-07-18",
  "return_date": "2022-07-25",
  "created_at": "2022-06-23T16:05:30.100Z",
  "updated_at": "2022-06-23T16:13:14.794Z"
}
POST/agent/bookings

Fetch All

This endpoint retrieves all bookings. Bookings are sorted by creation date, with the most recent bookings coming first.

Parameters

  • Name
    organisationrequired
    Type
    string
    Description

    The organisation ID that you want to fetch bookings for. You can find the organisation that you have access to by using the List all organisations method.

  • Name
    keyword
    Type
    string
    Description

    A customer name, booking reference or email address that you want to filter by.

  • Name
    skip
    Type
    integer
    Description

    Pagination offset. See the pagination section for details.

  • Name
    take
    Type
    integer
    Description

    Number of records to return. Defaults to 25, maximum 25. See the pagination section for details.

  • Name
    show-child-organisations
    Type
    boolean
    Description

    Whether to also show bookings for any of the requested organisation's child organisations.

  • Name
    type
    Type
    string
    Description

    Can be 'csv' or 'json', defaults to 'json'.

  • Name
    date_from
    Type
    date
    Description

    The booking departure date to fetch bookings from, in ISO 8601 format.

  • Name
    date_to
    Type
    date
    Description

    The booking departure date to fetch bookings to, in ISO 8601 format.

  • Name
    booking_reference
    Type
    string
    Description

    Allows you to find a booking by exact booking reference (not case sensitive).

Returns

Returns an array of Booking Models. In list responses, transactions only includes completed transactions and components is always empty; use Fetch One for the full booking.

Request

POST
/agent/bookings
import axios from 'axios';

const response = await axios.post(
  'https://api.felloh.com/agent/bookings',
  {
    organisation: 'X9876',
    keyword: 'james.dean@gmail.com',
    date_from: '2020-02-01',
    date_to: '2021-05-10',
    skip: 10,
    take: 20
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response (set using type parameter)

{
  "data": [
        {
          "id": "226009ab-ffe9-4c80-922b-982e8e7849f8",
          "gross_amount": 1000000,
          "currency": "GBX",
          "email": "james.dean@gmail.com",
          "atol_receipt_number": "233234234",
          "user": {
            "id": "e8c243ff-d000-4f81-ba57-94184d44dae2",
            "email": "tom@felloh.com"
          },
          "transactions": [
            {
              "id": "fe9afbbf-0854-48af-acec-1efd1bed229a",
              "amount": 56300,
              "status": "COMPLETE",
              "method": "ONLINE",
              "type": "CARD",
              "created_at": "2022-01-28T10:58:31.165Z",
              "completed_at": "2022-01-28T10:58:31.165Z"
            }
          ],
          "payment_links": [
            {
              "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
              "amount": 1000,
              "description": "Deposit for Bali",
              "expires_at": "2021-12-17T15:10:37.589Z",
              "created_at": "2021-11-17T15:10:37.589Z",
              "email": "tom@felloh.com",
              "currency": "GBX",
              "methods": {
                "open_banking": true,
                "card": true
              }
            }
          ],
          "package_type": {
            "id": "AGENT_OF_ATOL_HOLDER",
            "created_at": "2023-04-04T09:41:12.021Z"
          },
          "customer_name": "James Dean",
          "booking_reference": "XXX123789",
          "departure_date": "2022-07-18",
          "return_date": "2022-07-25",
          "created_at": "2022-06-23T16:05:30.100Z",
          "updated_at": "2022-06-23T16:13:14.794Z"
        }
    ],
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6",
    "count": 1
  }
}
GET/agent/bookings/:booking_id

Fetch One

This endpoint retrieves a specific booking by its ID.

Path Parameters

  • Name
    booking_id
    Type
    UUID
    Description

    The booking ID you wish to retrieve.

Returns

Returns a Booking Model

Request

GET
/agent/bookings/:booking_id
import axios from 'axios';

const bookingID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios.get(
  `https://api.felloh.com/agent/bookings/${bookingID}`,
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {
    "id": "226009ab-ffe9-4c80-922b-982e8e7849f8",
    "gross_amount": 1000000,
    "currency": "GBX",
    "email": "james.dean@gmail.com",
    "atol_receipt_number": "233234234",
    "user": {
      "id": "e8c243ff-d000-4f81-ba57-94184d44dae2",
      "email": "tom@felloh.com"
    },
    "components": [
      {
        "id": "8224bb6e-7d70-588b-82b8-316f2d71012e",
        "supplier": {
          "id": "6ab41ce7-36c8-5835-b997-492adb3d66e1",
          "name": "Felloh Travel - Packages",
          "created_at": "2022-06-28T17:27:59.616Z"
        },
        "amount": 56300,
        "booking_reference": "X1232JJ",
        "destination_air": "AMS",
        "type": "packages",
        "created_at": "2023-02-15T16:00:18.886Z"
      }
    ],
    "transactions": [
      {
        "id": "fe9afbbf-0854-48af-acec-1efd1bed229a",
        "amount": 56300,
        "status": "COMPLETE",
        "method": "ONLINE",
        "type": "CARD",
        "created_at": "2022-01-28T10:58:31.165Z",
        "completed_at": "2022-01-28T10:58:31.165Z"
      }
    ],
    "package_type": {
      "id": "AGENT_OF_ATOL_HOLDER",
      "created_at": "2023-04-04T09:41:12.021Z"
    },
    "customer_name": "James Dean",
    "booking_reference": "XXX123789",
    "departure_date": "2022-07-18",
    "return_date": "2022-07-25",
    "created_at": "2022-06-23T16:05:30.100Z",
    "updated_at": "2022-06-23T16:13:14.794Z"
  },
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}
PUT/agent/bookings

Create One

This endpoint allows you to create a new booking. Booking references are unique within an organisation: if a booking with the same booking_reference already exists, that existing booking is returned (with a 200 response) and no new booking is created.

Parameters

  • Name
    organisationrequired
    Type
    string
    Description

    The organisation ID in which you want to create the booking.

  • Name
    booking_referencerequired
    Type
    string
    Description

    Your reference for the booking

  • Name
    customer_namerequired
    Type
    string
    Description

    The customer's full name.

  • Name
    emailrequired
    Type
    string
    Description

    The customer's email address.

  • Name
    currency
    Type
    string
    Description

    The currency that booking is in, defaults to GBX. See the currency documentation for more information.

  • Name
    departure_date
    Type
    date
    Description

    The date when the booking departs.

  • Name
    return_date
    Type
    date
    Description

    The date when the booking returns.

  • Name
    gross_amount
    Type
    integer
    Description

    The total value of the booking.

  • Name
    package_type
    Type
    string
    Description

    The package type of the booking.

The ATOL receipt number cannot be set on creation; use Update One to set it afterwards.

Returns

Returns the created booking. The response contains the booking's id along with the fields you supplied, the organisation and user it was created under, and the linked customer.

Request

PUT
/agent/bookings
import axios from 'axios';

const response = await axios.put(
  'https://api.felloh.com/agent/bookings',
  {
    organisation: 'X9876',
    customer_name: 'James Dean',
    email: 'james@felloh.org',
    booking_reference: 'XXX123789',
    departure_date: '2022-07-18',
    return_date: '2022-07-25',
    gross_amount: 1000000,
    currency: 'GBX',
    atol_receipt_number: '233234234',
    package_type: 'AGENT_OF_ATOL_HOLDER'
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {
    "id": "226009ab-ffe9-4c80-922b-982e8e7849f8",
    "organisation": {
      "id": "X9876"
    },
    "user": {
      "id": "e8c243ff-d000-4f81-ba57-94184d44dae2"
    },
    "customer": {
      "id": "cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e"
    },
    "customer_name": "James Dean",
    "email": "james.dean@gmail.com",
    "booking_reference": "XXX123789",
    "departure_date": "2022-07-18",
    "return_date": "2022-07-25",
    "gross_amount": 1000000,
    "currency": "GBX",
    "package_type": null,
    "is_temporary": false,
    "created_at": "2022-06-23T16:05:30.100Z",
    "updated_at": "2022-06-23T16:05:30.100Z"
  },
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}
DELETE/agent/bookings/:booking_id

Delete One

This endpoint deletes a booking. The booking is soft-deleted; any transactions, payment links or scheduled payments already linked to it are left in place. The API key must have the booking-and-payment:delete:booking role or be the user that created the booking.

Path Parameters

  • Name
    booking_id
    Type
    UUID
    Description

    The booking ID you wish to delete.

Request

DELETE
/agent/bookings/:booking_id
import axios from 'axios';

const bookingID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios.delete(
  `https://api.felloh.com/agent/bookings/${bookingID}`,
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {},
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}
POST/agent/bookings/:booking_id

Update One

This endpoint allows you to update booking details.

Path Parameters

  • Name
    booking_id
    Type
    UUID
    Description

    The booking ID you wish to update.

Parameters

  • Name
    gross_value
    Type
    integer
    Description

    The total value of the booking, in the lowest denomination of the currency (e.g. pence).

  • Name
    gross_amount
    Type
    number
    Description

    Deprecated alias kept for backwards compatibility: the booking value in major units (e.g. pounds), which is multiplied by 100 before being stored. Prefer gross_value.

  • Name
    departure_date
    Type
    string
    Description

    The departure date of the booking.

  • Name
    return_date
    Type
    string
    Description

    The return date of the booking.

  • Name
    customer_name
    Type
    string
    Description

    The customer name for the booking.

  • Name
    email
    Type
    string
    Description

    The customer's email address for the booking.

  • Name
    package_type
    Type
    string
    Description

    The package type of the booking.

  • Name
    atol_receipt_number
    Type
    string
    Description

    The ATOL receipt number of the booking.

Request

POST
/agent/bookings/:booking_id
import axios from 'axios';

const bookingID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios.post(
  `https://api.felloh.com/agent/bookings/${bookingID}`,
  {
    gross_value: '2500',
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {},
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}
POST/agent/bookings/:booking_id/update-reference

Update Booking Reference

This endpoint allows you to update the booking reference for a booking. If another booking in the organisation already uses the new reference, the two bookings are merged: this booking's transactions and payment links are moved to the existing booking, this booking is deleted, and the response contains new_booking_id (the id of the booking they were moved to) instead of an empty object.

Path Parameters

  • Name
    booking_id
    Type
    UUID
    Description

    The booking ID you wish to update.

Parameters

  • Name
    booking_referencerequired
    Type
    string
    Description

    The new booking reference for the booking.

Request

POST
/agent/bookings/:booking_id/update-reference
import axios from 'axios';

const bookingID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios.post(
  `https://api.felloh.com/agent/bookings/${bookingID}/update-reference`,
  {
    booking_reference: 'test-1234'
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {},
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}