Technical Documentation
      Back to home
      1. Knowledge Base
      2. Webhooks & APIs
      3. Technical Documentation

      Managing Open and Work Hour Schedules using the API

      This article presents how to manage open and work hour schedules using the Booxi API.

      Please take note that examples and endpoints used in this article require a partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.

      Be reminded that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting.

      North America Europe
      api.booxi.com api.booxi.eu

       

      Before having a look at the API and its endpoints, let’s describe what open and work hour schedules are and how they impact availability.

      What are Open Hour Schedules?

      Open hours schedules are by definition the hours during which a merchant is doing business and taking bookings. While only one schedule can be active at a time, Booxi allows creating several schedules to meet specific needs or changing business hours throughout the year, i.e. end-of-the-year holidays, summer time, etc.

      open-hours

      What are Work Hour Schedules?

      Work hours schedules describe the period of time a member of staff is working or available for booking. A staff work schedule can be set by using one of the following options:

      • Open Hours
        For staff working during standard business hours, a merchant's open hours can be used to define their work schedule.
      • Weekly Work Schedule
        For staff requiring more flexible work hours, a weekly work schedule allows defining work hours on a day-by-day basis.
      • Calendar
        For staff with no fixed schedule, use the staff calendar to create available time slots.

      work-schedule-options

      Availability

      Merchant availability are determined by the open hour schedule currently active (marked with a green dot in the Back Office). Availability can be altered by assigning a different schedule or by creating a new one.

      Staff availability are determined by their work hour schedule (open hours, weekly work schedule or calendar) minus any busy time slots added to their calendar.

      Schedules API

      The Schedules API provides endpoints to retrieve, create, update and delete both merchant and staff schedules. Please take note that any operation performed on schedules will have an impact on availability and may result in limited booking opportunities. Make sure the operation to be performed will generate the expected result.

      Merchant Schedule 

      Retrieving a Merchant’s Schedules

      To retrieve schedules assigned to a merchant, use the GET/merchant/{merchantId}/schedule endpoint. Your request must minimally include a merchant Id.  Additional parameters are available to limit the request’s range.


      Mandatory Parameters

      Parameter Format Description

      merchantId

      merchantId={merchantId}

      Merchant from which schedules are retrieved from.


      Optional Parameters

      Parameter Format Description
      rangeStart rangeStart={date}
      rangeStart=2022-01-01      		 Beginning of the date range to retrieve schedules from.
      rangeEnd rageEnd={date}
      rangeStart=2024-01-01      		 End of the date range to retrieve schedules from.
      cursor cursor={cursor}
      "cursor": "sl_eJxjZGALcmVgYGdQTtjGAK"      		 A token to get the next set of results associated with a request.
      When the cursor is set, all other query parameters should NOT be set.


      Limitations

      • Retrieving schedules by date range is limited to 1 year in the past and 10 years in the future.

      Request URL for North America

      https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json" 

       

      You can test this API at the following links.

      For North America For Europe
      listMerchantSchedules listMerchantSchedules

       

      Successful JSON Response

      When the query is successful, the response will include schedules associated with the specified merchant for the range of time provided (if any).

      Here’s an example of a successful response:

      {
        "schedules": [
          {
            "id": 1,
            "name": "Holiday Season 2023",
            "description": "Holidays 2023",
            "start": "2023-12-21",
            "end": "2023-12-31",
            "weeklyHours": [
              {
                "dow": 1,
                "start": "10:00:00",
                "end": "18:00:00"
              }
            ]
          }
        ],
       "cursor": "sl_eJxjZGALcmVgYGdQTtjGAK"
      }

      Retrieving a Specific Merchant Schedule

      To retrieve a specific merchant schedule, use the GET/merchant/{merchantId}/schedule/{scheduleId} endpoint. Your request must minimally include a merchant Id and a schedule Id. 

       

      Mandatory Parameters

      Parameter Format Description
      merchantId merchantId={merchantId}
      merchantId=8099      		 Merchant the schedule is retrieved from.
      scheduleId scheduleId={scheduleId}
      scheduleId=13865      		 The id associated with the schedule to retrieve.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"

       

      You can test this API at the following links.

      For North America For Europe
      getMerchantSchedule getMerchantSchedule

       

      Successful JSON Response

      When the query is successful, the response will include the requested schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 1,
        "name": "Holiday Season 2023",
        "description": "Holidays 2023",
        "start": "2023-12-21",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      Creating a New Merchant Schedule

      To create a new merchant schedule, use the POST/merchant/{merchantId}/schedule endpoint. Your request must minimally include a merchant Id and a request body.  

       

      Mandatory Parameters

      Parameter Format Description
      merchantId merchantId={merchantId}
      merchantId=8099      		 Merchant schedules are retrieved from.
      requestbody see below for details on its content. All details related to the new schedule to create.

       

      Limitations

      • Creating overlapping schedules is neither permitted nor supported.

      Request URL for North America

      https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule

      cURL

      curl -X POST
      "https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"
      -d  "{\"id\":1,\"name\":\"Holiday Season 2023\",\"description\":\"Holidays 2023\",
      \"start\":\"2023-12-21\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"10:00:00\",\"end\":\"18:00:00\"}]}"

      Request Body

      {
        "name": "Holiday Season 2023",
        "description": "Holidays 2023",
        "start": "2023-12-21",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 0,
            "start": "10:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 2,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      You can test this API at the following links.

      For North America For Europe
      createMerchantSchedules createMerchantSchedules

       

      Successful JSON Response

      When the query is successful, the response will include the new schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 1,
        "name": "Holiday Season 2023",
        "description": "Holidays 2023",
        "start": "2023-12-24",
        "end": "2023-12-31",
        "weeklyHours": [
          {
             "dow": 0,
            "start": "10:00:00",
            "end": "18:00:00"
          },
          {
             "dow": 1,
             "start": "10:00:00",
             "end": "18:00:00"
          },
          {
             "dow": 2,
             "start": "10:00:00",
             "end": "18:00:00"
          }
        ]
      }

       

      Updating a Merchant Schedule

      To update/modify a merchant schedule, use the PUT/merchant/{merchantId}/schedule/{scheduleId} endpoint. Your request must minimally include a merchant Id, a schedule Id and a request body. 

       

      Mandatory Parameters

      Parameter Format Description
      merchantId merchantId={merchantId}
      merchantId=8099      		 Merchant schedules are retrieved from.
      scheduleId scheduleId={scheduleId}
      scheduleId=13865      		 The id associated with the schedule to retrieve.
      requestBody see below for details on its content. All details related to the schedule to update.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"
      -d  "{\"id\":1,\"name\":\"Holiday Season 2023\",\"description\":\"Holidays 2023\",
      \"start\":\"2023-12-24\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"10:00:00\",\"end\":\"18:00:00\"}]}" 

      Request Body

      {
        "name": "Holiday Season 2023",
        "description": "Holidays 2023",
        "start": "2023-12-24",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      You can test this API at the following links.

      For North America For Europe
      updateMerchantSchedule updateMerchantSchedule

       

      Successful JSON Response

      When the query is successful, the response will include the updated schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 1,
        "name": "Holiday Season 2023",
        "description": "Holidays 2023",
        "start": "2023-12-24",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      Deleting a Merchant Schedule

      To delete an existing merchant schedule, use the DELETE/merchant/{merchantId}/schedule/{scheduleId} endpoint. Your request must minimally include a merchant Id and a schedule Id.  Please take note that this operation cannot be undone and may impact a merchant’s availability.

      Mandatory Parameters

      Parameter Format Description
      merchantId merchantId={merchantId}
      merchantId=8099      		 Merchant schedules are retrieved from.
      scheduleId scheduleId={scheduleId}
      scheduleId=13865      		 The id associated with the schedule to retrieve.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/merchant/YOUR_MERCHANT_ID/schedule/YOUR_SCHEDULE_ID" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"

       

      You can test this API at the following links.

      For North America For Europe
      listMerchantSchedules listMerchantSchedules

       

      Successful JSON Response

      When the query is successful, the response will include the deleted schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 1,
        "name": "Holiday Season 2023",
        "description": "Holidays 2023",
        "start": "2023-12-24",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

      Staff Schedule 

      Retrieving a Staff's Schedules

      To retrieve schedules assigned to a member of staff, use the GET/staff/{staffId}/schedule endpoint. Your request must minimally include a staff Id.  Additional parameters are available to limit the request’s range.

       

      Mandatory Parameters

      Parameter Format Description
      staffId staffId={staffId}
      staffId=21750      		 Staff for which schedules are retrieved from.

       

      Optional Parameters

      Parameter Format Description
      rangeStart rangeStart={date}
      rangeStart=2022-01-01      		 Beginning of the date range to retrieve schedules from.
      rangeEnd rageEnd={date}
      rangeStart=2024-01-01      		 End of the date range to retrieve schedules from.
      cursor cursor={cursor}
      "cursor": "sl_eJxjZGALcmVgYGdQTtjGAK"      		 A token to get the next set of results associated with a request.
      When the cursor is set, all other query parameters should NOT be set.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json" 

       

      You can test this API at the following links.

      For North America For Europe
      listStaffSchedules listStaffSchedules

       

      Successful JSON Response

      When the query is successful, the response will include schedules associated with the member of staff for the range of time provided (if any).

      Here’s an example of a successful response:

      {
        "schedules": [
           {
              "id": 2,
              "name": "Fourth Quarter 2023",
              "description": "4TH-2023",
              "start": "2023-10-01",
              "end": "2023-12-31",
              "weeklyHours": [
                 {
                    "dow": 1,
                    "start": "10:00:00",
                    "end": "18:00:00"
                 },
                 {
                    "dow": 2,
                    "start": "10:00:00",
                    "end": "18:00:00"
                 }
               ]
            }
         ],
         "cursor": "sl_eJxjZGALcmVgYGdQTtjGAK"
      }

       

      Retrieving a Specific Staff Schedule

      To retrieve a specific staff schedule, use the GET/staff/{staffId}/schedule/{scheduleId} endpoint. Your request must minimally include a staff Id and a schedule Id.  

       

      Mandatory Parameters

      Parameter Format Description
      staffId staffId={staffId}
      stafId=21750      		 Staff for which the schedule is retrieved from.
      scheduleId scheduleId={scheduleId}
      scheduleId=13865      		 The id associated with the schedule to retrieve.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"

       

      You can test this API at the following links.

      For North America For Europe
      getStaffSchedule getStaffSchedule

       

      Successful JSON Response

      When the query is successful, the response will include the requested schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 2,
        "name": "Fourth Quarter 2023",
        "description": "4TH-2023",
        "start": "2023-10-01",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 2,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      Creating a New Staff Schedule

      To create a new staff schedule, use the POST/staff/{staffId}/schedule endpoint. Your request must minimally include a staff Id and a request body.  

       

      Mandatory Parameters

      Parameter Format Description
      staffId staffId={staffId}
      stafId=21750      		 Staff for which the schedule is retrieved from.
      requestBody see below for details on its content. All details related to the new schedule to create.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule

      cURL

      curl -X POST
      "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"
      -d  "{\"id\":1,\"name\":\"Holiday Season 2023\",\"description\":\"Holidays 2023\",
      \"start\":\"2023-12-21\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"10:00:00\",\"end\":\"18:00:00\"}]}"

      Request Body

      {
        "name": "Fourth Quarter 2023",
        "description": "4TH-2023",
        "start": "2023-10-01",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 0,
            "start": "10:00:00",
            "end": "18:00:00"
          },    
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 2,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      You can test this API at the following links.

      For North America For Europe
      createStaffSchedules createStaffSchedules

       

      Successful JSON Response

      When the query is successful, the response will include the new schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 2,
        "name": "Fourth Quarter 2023",
        "description": "4TH-2023",
        "start": "2023-10-01",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 0,
            "start": "10:00:00",
            "end": "18:00:00"
          },    
          {
            "dow": 1,
            "start": "10:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 2,
            "start": "10:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      Updating a Staff Schedule

      To update/modify a staff schedule, use the PUT/staff/{staffId}/schedule/{scheduleId} endpoint. Your request must minimally include a staff Id, a schedule Id and a request body.  

       

      Mandatory Parameters

      Parameter Format Description
      staffId staffId={staffId}
      stafId=21750      		 Staff for which the schedule is retrieved from.
      scheduleId scheduleId={scheduleId}
      scheduleId=13865      		 The id associated with the schedule to retrieve.
      requestBody see below for details on its content. All details related to the schedule to update.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"
      -d  "{\"id\":2,\"name\":\"Fourth Quarter 2023\",\"description\":\"4TH-2023\",
      \"start\":\"2023-10-01\",\"end\":\"2023-12-31\",\"weeklyHours\":[{\"dow\":1,\"start\":\"12:00:00\",\"end\":\"18:00:00\"},{\"dow\":2,\"start\":\"12:00:00\",\"end\":\"18:00:00\"}]}" 

      Request Body

      {
        "name": "Fourth Quarter 2023",
        "description": "4TH-2023",
        "start": "2023-10-01",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "12:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 2,
            "start": "12:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      You can test this API at the following links.

      For North America For Europe
      updateStaffSchedule updateStaffSchedule

       

      Successful JSON Response

      When the query is successful, the response will include the updated schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 2,
        "name": "Fourth Quarter 2023",
        "description": "4TH-2023",
        "start": "2023-10-01",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "12:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 2,
            "start": "12:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

      Deleting a Staff Schedule

      To delete an existing staff schedule, use the DELETE/staff/{staffId}/schedule/{scheduleId} endpoint. Your request must minimally include a staffId and a schedule Id.  Please take note that this operation cannot be undone and may impact staff availability.

       

      Mandatory Parameters

      Parameter Format Description
      staffId staffId={staffId}
      stafId=21750      		 Staff for which the schedule is retrieved from.
      scheduleId scheduleId={scheduleId}
      scheduleId=13865      		 The id associated with the schedule to retrieve.

       

      Request URL for North America

      https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID

      cURL

      curl -X GET
      "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/schedule/YOUR_SCHEDULE_ID" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json"

       

      You can test this API at the following links.

      For North America For Europe
      deleteStaffSchedule deleteStaffSchedule

       

      Successful JSON Response

      When the query is successful, the response will include the deleted schedule and its details.

      Here’s an example of a successful response:

      {
        "id": 2,
        "name": "Fourth Quarter 2023",
        "description": "4TH-2023",
        "start": "2023-10-01",
        "end": "2023-12-31",
        "weeklyHours": [
          {
            "dow": 1,
            "start": "12:00:00",
            "end": "18:00:00"
          },
          {
            "dow": 2,
            "start": "12:00:00",
            "end": "18:00:00"
          }
        ]
      }

       

       

      Status Codes & Error Messages

      The API returns data in a JSON format as well as standard HTTP status codes.

      Code Status Description
      200 Ok The request was completed successfully.
      400 Bad Request Error caused by an invalid request.
      Example: requesting a resource using an incorrect ID.
      401 Unauthorized The request hasn’t been completed because it lacks valid authentication credentials.
      Example: Using an incorrect API Key.
      403 Forbidden The request hasn’t been completed because it lacks appropriate permissions.
      Example:. Your API key doesn’t grant access to the requested resource (using a merchant API key where a partner API key is expected).
      404 Not Found The requested resource cannot be found on the server.
      Example: requesting a resource that has been deleted.
      409 Conflict The request conflicts with the current state of the targeted resource. 
      Example: creating a new time slot that overlaps with an existing one.
      500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request.
      Example: a connection to the server cannot be established.

      Limitations

      • Schedules shown in the Back Office (“My Business” > “Open hours” and “Personnel” > “Work schedule” > “Weekly work schedule”) are limited to 100 entries. If you create schedules for individual days (e.g.: from Jan 1-Jan 1, Jan 2-Jan 2, etc.), your schedule count may be higher than 100 and therefore some of your data will not be shown. For this reason, we strongly recommend creating schedules for a longer period of time, such as weekly, bi-weekly, monthly, yearly or seasonal (see here for more info); this is in fact how the schedule functionality is intended to be used.
      • Creating overlapping schedules is neither permitted nor supported.
      • Retrieving schedules by date range is limited to one year in the past and 10 years in the future.
      • The authentication method requires a secure environment.
      • The endpoint must not be exposed on a webpage but rather server side.
      • Endpoints may have their own limitations, please consult our online swagger for more information.
      • Calls per API key shall not exceed 5 requests per second with a maximum of 300 requests per minute. Exceeding this quota will return a 429 error. Respecting this quota and handling any 429 errors are the responsibility of the client. It is recommended to make API calls with an interval of at least 10 milliseconds between each request. Any API calls generating 400 errors will count as double requests for the quota.
      • The use of Booxi API is solely authorized to conduct legal business by the client or a consultant under contractual agreement. Any usage for spam or reported as abusive is strictly prohibited and will result in the revocation of the API access. It is also prohibited to resell the use of the API. For further details, please consult our terms of service.

      References 

      Americas: https://api.booxi.com/doc/booking.html

      Europe: https://api.booxi.eu/doc/booking.html

       

      Where to find API keys:

      • Your Merchant API key can be found in the Back Office, section My Business / Details.
      • Your Partner API key must be requested to your Booxi Account Manager. The Partner API key must only be used in server-side (backend) code to keep it a secret.