Booking with the Basket API

The public bookings API is ideal for simple booking journeys however depending on your project requirements you may need to use the basket APIs instead. If you have a long sign up form and want to ensure that a customers’ selected time is held while they fill in their details prior to completing the booking process this can be achieved using the basket API. Additionally if you want to enable the customers to book multiple items simultaneously the basket API is appropriate.

An important difference with the basket API is that once a basket is initialised using the add_item API call subsequent requests for the basket must be correctly authenticated. The response for the add_item call will include an Auth-Token header. The same auth token must be included in the checkout request.

Basket API Sequence Diagram

Fetch services

Assuming we already know the location for the appointment (represented by the company_id) typically the customer will want to know what services can be booked and how much they cost.

Get Services API

Endpoint:

https://{host}/api/v3/{company_id}/services

Request:

curl https://example.jrni.com/api/v3/1/services -H App-Id:1234

Response:

{
  "total_entries": 2,
  "_embedded": {
    "services": [
      {
        "name": "Tennis Coaching",
        "description": "Individual coaching is the fastest way to improve your tennis, whether a beginner or experienced club player.",
        "durations": [
          30,
          60
        ],
        "prices": [
          1000,
          1500
        ],
        "listed_durations": [
          20,
          50
        ],
        "booking_time_step": 30,
        "duration_unit": "minute",
        "min_bookings": 1,
        "max_bookings": 2,
        "_links": {
          "self": "https://example.bookingbug.com/api/v3/1/services/1",
          "times": {
            "href": "https://example.bookingbug.com/api/v3/1/time_data?service_id=1{&event_id,date,end_date,location,person_id,resource_id,duration,single,num_resources,group_id,resource_ids,time_zone,ignore_booking,person_group_id,people_ids,is_admin}",
            "templated": true
          }
        }
      },
      {
        "name": "Tennis Coaching Day",
        "description": "Ideal for improvers and seasoned tennis players alike, this professional coaching day, is the perfect chance to sharpen skills and boost performance on the court.",
        "durations": [
          1
        ],
        "prices": [
          6000
        ],
        "listed_durations": [
          1
        ],
        "duration_unit": "day",
        "min_bookings": 1,
        "max_bookings": 1,
        "_links": {
          "self": "https://example.bookingbug.com/api/v3/1/services/2"
        }
      }
    ]
  },
  "_links": {
    "self": "https://example.bookingbug.com/api/v3/1/services"
  }
}

Fetch time

Once the customer has selected a service we can use the service_id along with a date to retrieve the available times.

Get Time API

Endpoint:

https://example.jrni.com/api/v3/{company_id}/times{?service_id,start_date,duration}

Request:

curl https://example.jrni.com/api/v3/1/times?service_id=1&start_date=2018-01-01 \
  -H App-Id:1234

Response:

{
  "_embedded": {
    "times": [
      {
        "start": "2018-01-01T09:00:00+01:00",
        "available": true,
        "durations": [60],
        "prices": [],
        "_links": {
          "self": {
            "href": "https://example.jrni.com/api/v3/admin/1/times2018-01-01T09:00:00+01:00?service_id=1"
          }
        }
      },
      {
        "start": "2018-01-01T10:00:00+01:00",
        "available": true,
        "durations": [60],
        "prices": [],
        "_links": {
          "self": {
            "href": "https://example.jrni.com/api/v3/admin/1/times2018-01-01T10:00:00+01:00?service_id=1"
          }
        }
      },
      {
        "start": "2018-01-01T11:00:00+01:00",
        "available": true,
        "durations": [60],
        "prices": [],
        "_links": {
          "self": {
            "href": "https://example.jrni.com/api/v3/admin/1/times2018-01-01T11:00:00+01:00?service_id=1"
          }
        }
      },
      {
        "start": "2018-01-01T12:00:00+01:00",
        "available": true,
        "durations": [60],
        "prices": [],
        "_links": {
          "self": {
            "href": "https://example.jrni.com/api/v3/admin/1/times2018-01-01T12:00:00+01:00?service_id=1"
          }
        }
      },
      {
        "start": "2018-01-01T13:00:00+01:00",
        "available": true,
        "durations": [60],
        "prices": [],
        "_links": {
          "self": {
            "href": "https://example.jrni.com/api/v3/admin/1/times2018-01-01T13:00:00+01:00?service_id=1"
          }
        }
      },
      {
        "start": "2018-01-01T14:00:00+01:00",
        "available": true,
        "durations": [60],
        "prices": [],
        "_links": {
          "self": {
            "href": "https://example.jrni.com/api/v3/admin/1/times2018-01-01T14:00:00+01:00?service_id=1"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href: "https://example.jrni.com/api/v3/1/times?service_id=1&start_date=2018-01-01"
    }
  }
}

Add to basket

Endpoint:

https://{host}/api/v3/{company_id}/basket/add_item

Request:

curl https://example.jrni.com/api/v3/1/basket/add_item -H App-Id:1234 -X POST \
  -d '{
    "service_id": 1,
    "date": "2018-01-01",
    "time": 540,
    "person_id": 2,
    "resource_id": 1
  }'

Response:

{
  "company_id": 1,
  "total_price": 1000,
  "_embedded": {
    "items": [{
      "id": "8d208dcd71b76edc",
      "date": "2018-01-01",
      "service_id": 1,
      "person_id": 2,
      "resource_id": 1,
      "time": 540,
      "_links": {
        "self": {
          "href": "https://example.jrni.com/api/v3/1/basket/8d208dcd71b76edc"
        }
      }
    }]
  },
  "_links": {
    "self": {
      "href": "https://example.jrni.com/api/v3/1/basket"
    }
  }
}

Response headers:

Auth-Token: xyz

Create client

Endpoint:

https://{host}/api/v3/{company_id}/client

Request:

curl https://example.jrni.com/api/v3/1/client -H App-Id:1234 -X POST \
 -d '{
   "first_name": "John",
   "last_name": "Doe",
   "email": "jdoe@example.com"
 }'

Response:

{
  "id": 1295,
  "first_name": "John",
  "last_name": "Doe",
  "email": "jdoe@example.com"
}

Checkout basket

Use the ID of the created customer in the payload of the request and use the Auth-Token header from the add item response.

Endpoint:

https://{host}/api/v3/{company_id}/basket/checkout

Request:

curl https://example.jrni.com/api/v3/1/basket/checkout -H App-Id:1234 \
  -H Auth-Token:xyz -X POST \
  -d '{
    "client": {
      "id": 1295
    }
  }'