Menu
GUIDE > EVENTS

Availability Events

You can send bookings to Bedful using the endpoints documented on this page, and receive bookings from bedful by setting up an integration and corresponding webhooks. If a site on Bedful sets up an integration with your API, Bedful will accept events from your server in JSON format in order to create or update bookings from your service, and send events to your endpoint when a booking is created or updated.

Creating Bookings

The acceptable fields to set on a booking are detailed in the JSON below. When creating bookings, the ID param is not required as an id will be assigned on creation. You may pass a reference to indicate the ID on your external system in your preferred format. It is stored as a string so it supports numeric or alphanumeric references.  

curl https://devapi.bedful.com/bookings/external/create \
-u BEDFUL_KEY: \
-H  "Content-Type: application/json" \
--data '{"site_id":123,"unit_ids":325,"reference":"1321324@anytime.com","starts_at":"2022-03-01T00:00:00Z","ends_at":"2022-03-04T00:00:00Z"}'

REQUIRED fields are:

  • Site ID – the Bedful site id in question
  • Unit IDs – the Bedful unit id(s) the booking is on - this may be a single integer or an array of integers
  • Status – the Bedful status of your booking see Booking Status for more information on possible values
  • Starts At – the date the booking starts, at 0 hours on the arrival day
  • Ends At – the date the booking ends, at 0 hours on the departure day
  • Reference – your UNIQUE string reference for the booking - this should be unique across all your bookings but does not have to be globally unique (e.g. may overlap bedful ids) – while not required this is desirable on every booking

All other fields are optional, though we strongly suggest if your partners are using your integration to get bookings into bedful that you provide all the information they might want in order to recognise bookings (for example guest name and email).

Events without a live integration for your channel on the site concerned will be ignored.

An example of a simple booking posted to the API is as follows

{
  "reference": "234098234098234@exampleservice",
  "site_id": 123,
  "unit_ids": 325,
  "status": 100,
  "starts_at": "2006-01-02T00:00",
  "ends_at": "2006-01-02T00:00",
  "name": "John Smith",
  "email": "example@example.com"
}
A more complex booking might be: 
{
  "reference": "234098234098234@exampleservice",
  "site_id": 123,
  "unit_ids": 325,
  "status": 100,
  "starts_at": "2006-01-02T15:04:05Z07:00",
  "ends_at": "2006-01-02T15:04:05Z07:00",
  "name": "John Smith",
  "email": "example@example.com",
  "telephone": "098234098234",
  "address": "12 Example St",
  "postal_code": "EXA MPL",
  "country": "UK",
  "adults": 2,
  "children": 2,
  "ages": "3,4",
  "paid": 1200,
  "price": 1200,
  "commission": 12,
  "fees": 12,
  "security_deposit_amount": 24000,
  "currency_id": 1,
  "currency_rate": 1
}

For full details on booking record fields, see Booking Fields - the record returned from this endpoint is a more limited subset of booking fields which should interest external providers.

After creating an event you should record the Bedful booking id (the "id" field) in your system, so that you can update the booking if it is edited.

Multiple-unit bookings

Bedful bookings may contain several units, so you should be prepared for this eventuality. Multiple-unit bookings are less common than single-unit bookings but are relatively commonplace. If your system stores one booking per unit, when creating and updating bookings you'll need to be aware of this. You may wish to prepend the bedful unit id to the bedful booking id to generate your own unique identifier.

Unavailable Periods – blocking availability

Unavailable periods are represented on Bedful as bookings with status 12. If you have a separate concept of unavailable periods you should create and update them as bookings on the Bedful side using the events above.

{
  "reference": "234098234098234@exampleservice",
  "site_id": 123,
  "unit_ids": 325,
  "status": 12,
  "starts_at": "2006-01-02T00:00",
  "ends_at": "2006-01-02T00:00"
}

Seasons – when the site is open

Bedful records seasons on sites in order to represent periods where the site is completely unavailable for booking. We recommend you use seasons to communicate periods where the site is closed with the Bedful system rather than long unavailable blocks.

Updating Bookings

To update booking information, simply POST an updated record with a id (booking id) and site id to the same endpoint, with any information that has changed. The record does not have to be complete but should contain at least a site ID and a booking ID or Reference. 

curl https://devapi.bedful.com/bookings/external/update \
-u BEDFUL_KEY: \
-H  "Content-Type: application/json" \
--data '{"id":123,"site_id":123,"status":100}'

An example of the JSON to update a booking: 

{ 
 "id": 123,
 "site_id": 123, 
 "name": "New Name"
}

REQUIRED fields for update are:

  • Site ID – the site id in question
  • Your Reference OR Bedful ID – your unique booking reference or the bedful booking id
  • Other fields are optional, for a full list of fields see Booking Fields

Cancelling Bookings

To cancel a booking, send an update event with a status of 11 (Cancelled).

{ 
 "id": 123,
 "site_id": 123, 
 "status": 11
}

Receiving Bookings from Bedful

If a site on Bedful sets up an integration with your API, Bedful will send an event to that endpoint for you every time a booking is created, cancelled or updated.

The endpoint should receive POST requests with a body containing the booking details in JSON format.

JSON posted to your service for a new booking will be of the form:

{
  "event": "cancel",
  "id": 123456,
  "channel_id": 1,
  "reference": "",
  "site_id": 123,
  "user_id": 456789,
  "status": 11,
  "created_at": "2020-10-21T11:38:00Z",
  "updated_at": "2021-06-24T12:31:25Z",
  "starts_at": "2021-06-21T00:00:00Z",
  "ends_at": "2021-06-25T00:00:00Z",
  "name": "Guest Name",
  "email": "guestemail@example.com",
  "telephone": "12345678910",
  "address": "Guest Address",
  "postal_code": "Guest Postcode",
  "country": "United Kingdom",
  "adults": 2,
  "children": 2,
  "ages": "40, 40, 2, 0",
  "paid": 70000,
  "price": 70000,
  "discount_amount": 0,
  "commission": 0,
  "fees": 1020,
  "security_deposit_amount": 15000,
  "currency_id": 1,
  "currency_rate": 1,
  "items": [
    {
      "external_id": test_unit_external_id,
      "unit_id": 123456,
      "accommodation_price": 70000,
      "ages": 40,40,2,0
    },
    ]
}

JSON posted will include an 'event' field that specifies whether this is a 'cancel', 'create' or 'update' event. Each booking includes one or more items, which represent occupancy of an individual unit. Site owners may define a map of Bedful unit IDs to the corresponding IDs in your system; these will then be included via the external_id field.

Errors and Retries

The API uses the standard HTTP error codes to report results, and error codes and their meanings are summarised below. Broadly, if you receive a 40x error, it means the error is in the request and you should not retry with the same parameters. If you receive a 50x error, this means the error was on our side and may be a transient one. Most errors will also report more detail in the json response.

  • 200 – OK – the request was successful
  • 302 – Found – the request was successful and a redirect to the resource
  • 400 – Bad Request – please check the parameters and request body before trying again
  • 401 – Not Authorised – please check the credentials before trying again
  • 404 – Not Found – the resource requested could not be found, please check the ids requested
  • 500 – Internal Error – the server encountered an error. Please retry with exponential backoff (i.e. retry in 1 minute, 10 minutes, 100 minutes).