PUT Update booking state

Perform an action on a booking to update its state.

For a tutorial on how to perform the "confirm" action, head on over to our help center: http://help.timekit.io/working-with-the-api/bookings/confirming-bookings

Please also check out our Action links article on how you can create signed links that are safe to share with your customers, like links in an email. A link stays valid for as long as the booking's current state allows its action. Use this for your customers to confirm, cancel or perform any other action on a booking without involving your backend.

Changing the state of a booking is done via actions. Some actions will autoplay and some can be manually triggered via this endpoint.

The actions available for a given booking are dependent on which graph the booking follows and which state the booking is in.

Some actions can take inputs/settings. For example, in the confirm_decline graph, the decline action can take a message and be enabled/disabled. Please see the reference for the relevant graph to see which inputs are valid.

If the action you're performing results in a final state where the booking cannot take other actions (e.g. completed, paid, declined etc), the response will have a completed key set to true.

Common actions

Confirm a booking: use the action confirm

Decline a booking: use the action decline

Cancel a booking: use the action cancel (if the resource cancels) or cancel_by_customer (if its the customer that initiates the cancellation). Bookings on the group_customer graph have no cancel action: use cancel_by_owner or cancel_by_customer instead.

Complete a booking: use the action complete (use this if you want to let Timekit know 'exactly' when you feel the event should be set to completed. By default, Timekit sets events to 'completed' one hour after the actual completion time). You can read more about this here: https://developers.timekit.io/reference/graphs

Endpoint

PUT https://api.timekit.io/v2/bookings/:id/:action

Parameters

Name	In	Type	Required	Default	Description
`id`	path	string	yes		The ID of the booking
`action`	path	string	yes		Which action to trigger
`apply_to_bulked_bookings`	body	boolean		true	If the booking is bulked and related, the action will be replicated to the other bulked bookings, this parameter can disable this default behaviour. Please see https://reference.timekit.io/reference#bookingsbulk

Request examples

The example adds include=attributes,calendar,customers,available_actions so those objects appear in the response. Without include, the response only has the basic booking fields and, once the booking has a calendar event, what, where, description, start, end, rsvp and allDay.

curlcurl --request PUT \
  --url 'https://api.timekit.io/v2/bookings/58190fc6-1ec0-4ebb-b627-7ce6aa9fc703/confirm?include=attributes,calendar,customers,available_actions' \
  --header 'Content-Type: application/json' \
  --user :live_api_key_7nzvc7wsBQQISLeFSVhROys9V1bUJ1z7 \
  --data '{}'

Response examples

200

json{
  "data": {
    "id": "58190fc6-1ec0-4ebb-b627-7ce6aa9fc703",
    "graph": "confirm_decline",
    "state": "confirmed",
    "completed": false,
    "created_at": "2016-02-11T11:58:45+0100",
    "updated_at": "2016-02-11T11:58:47+0100",
    "rsvp": "accepted",
    "what": "Catch the lightning",
    "where": "Courthouse, Hill Valley, CA 95420, USA",
    "description": "The lightning strikes at 10:04 PM exactly! I need you to be there Doc!",
    "allDay": false,
    "end": "1955-11-12T22:15:00-0700",
    "start": "1955-11-12T21:30:00-0700",
    "available_actions": [
      "complete",
      "cancel",
      "reschedule_by_customer",
      "cancel_by_customer"
    ],
    "attributes": {
      "event_info": {
        "start": "1955-11-12T21:30:00-07:00",
        "end": "1955-11-12T22:15:00-07:00",
        "what": "Catch the lightning",
        "where": "Courthouse, Hill Valley, CA 95420, USA",
        "description": "The lightning strikes at 10:04 PM exactly! I need you to be there Doc!"
      }
    },
    "calendar": {
      "id": "bfa0b9fa-36aa-4ae6-8096-f3b20fbed1d2",
      "name": "Important encounters with Marty",
      "display_name": "Important encounters with Marty",
      "description": "Througout time, Marty and I really need to meet in order for the world not to collapse into Biffy cazyness.",
      "foregroundcolor": "#000000",
      "backgroundcolor": "#FFFFFF",
      "created_at": "2016-02-15T13:21:42+0100",
      "updated_at": "2016-02-15T13:21:42+0100"
    },
    "customers": [
      {
        "id": "a728e860-99c7-4009-8843-7d9ac5d7f53f",
        "name": "Marty McFly",
        "email": "marty.mcfly@timekit.io",
        "phone": "(916) 555-4385",
        "voip": "McFly",
        "timezone": "America/Los_Angeles"
      }
    ]
  }
}