StackDrivenDesigns Appointment API

For independent sylists, or neighborhood shops, or any service provider that needs a quick appointment solution, we got you covered!

Understanding the Appointment Lifecycle

The Appointments API is built around a structured, secure workflow that helps shops and clients manage appointments in real time. Everything begins with an Order Session, which acts like a short-lived "container" for one or more appointments. This session stays open for 30 minutes, giving the client time to select services, choose a stylist, and build out their appointments. Once the client is ready, they submit the order session, which attaches the customer's contact information and transitions the included appointments to an initial status of Requested. This status indicates that the appointments are pending stylist approval.

Each appointment created through this API flows through a well-defined set of statuses to represent its lifecycle. Understanding this workflow is critical for managing updates, cancellations, and confirmations effectively.

• Requested – This is the initial status once an appointment is added via the AddAppointment endpoint and submitted using SubmitOrderSession. It indicates that the client has requested the time.
• Confirmed – This status is manually updated by the client or system when the stylist has acknowledged and accepted the appointment. Use the ConfirmAppointment endpoint to update an appointment to this status.
• In Progress – Automatically set when the appointment’s start time begins. The ExecuteInternalProcesses endpoint handles this update during scheduled polling or notification logic.
• Finished – Automatically updated once the appointment’s end time has passed. This is handled in the same automated cycle as “In Progress.”
• Canceled – If the client cancels before the appointment is finished, the status is set to “Canceled.” This is triggered by the CancelAppointment endpoint.

ShopKey & API Key Security

Every request to the Appointments API requires two keys for validation: your X-Shop-Key and your X-RapidAPI-Key. These keys work together to authenticate your session and identify which shop the request belongs to.

• X-Shop-Key is a unique identifier assigned to your shop when you onboard the platform. It is required in every request header and should be treated as confidential.
• X-RapidAPI-Key is your unique access key issued by RapidAPI. It authorizes you as a subscriber and works in tandem with the ShopKey to validate API usage.
• Both keys must match an active and valid record in the system. If the keys are mismatched, missing, or inactive, your request will be denied with an Unauthorized status response.
• We recommend storing these keys securely on the client side and never exposing them in public or client-side JavaScript.
• If your keys are ever compromised, contact support immediately to revoke and regenerate them.

These keys are checked automatically through the ShopAuthenticator.CheckApiKeys logic that runs on all protected endpoints. No appointment-related action is permitted without passing this validation.

Order Sessions and Expiration

An Order Session represents a temporary window of time during which a customer can build a set of appointments as part of a single transaction. This allows customers to book multiple appointments under one OrderNumber before finalizing their submission.

• To begin, the client must call the CreateOrderSession endpoint. This generates a unique OrderNumber and an ExpirationDate (usually 30 minutes from creation).
• During this time, appointments created with that OrderNumber are held in a temporary state, allowing edits, confirmations, or cancellations.
• If the expiration time passes without the order being submitted using SubmitOrderSession, the entire session becomes invalid and the timeslots are released.
• This expiration system exists because timeslots are being claimed behind the scenes as appointments are added. It prevents scenarios where customers hold timeslots indefinitely without completing their booking.

Once the order is submitted, the system finalizes the session and marks the included appointments as Requested. After submission, no additional appointments can be added to that OrderNumber.

Availability and Time Slot Claiming

The appointment system is built around a 30-minute time slot structure derived from each shop’s submitted weekly schedule. These time slots define when stylists are generally available to accept appointments. For example, if a stylist is open from 9:00 AM to 5:00 PM, the day is divided into time slots like 09:00, 09:30, 10:00, and so on.

When a client requests an appointment of a specific duration (e.g., 60 or 90 minutes), the system must identify a series of consecutive time slots that are not blocked, taken, or restricted. The number of slots required is calculated based on the appointment duration (60 minutes = 2 slots, 90 minutes = 3 slots, etc.).

The availability engine checks each time slot using a smart function that not only validates whether the slot is free (IsAvailable) but also whether it can be used as the starting point for a full appointment of the requested duration. This is reflected in the new field StartTimeEligible. A time slot may be available, but if there is not enough availability afterward to satisfy the full appointment length, it is marked as StartTimeEligible: false. This distinction helps ensure the integrity of the booking experience and prevents broken or partially-booked sessions. Here is a visual that represents a typical daily schedule for @FadeMasterMike (assuming a search for 60 consecutive minutes of availability):

Once an timeslot is "chosen" using the AddAppointment endpoint, the time slot is softly claimed to temporarily reserve them until the session is finalized or expires. If the session expires without submission, the time slot is automatically released back to the system. This mechanism prevents double-bookings and provides a seamless user experience while maintaining real-time availability accuracy. If you were to try to book an appointment that is not marked available or start time eligible, you will receive an http error.

Example

Let’s say the requested duration is 60 minutes (two 30-minute slots), and the availability looks like this:

                    
                        curl -X POST "https://[your rapid api prefix]/stylist/getavailabilityoutlookbyday" \
                        -H "Content-Type: application/json" \
                        -H "X-RapidAPI-Key: your-rapidapi-key-here" \
                        -H "X-Shop-Key: your-shop-key-here" \
                        -d '{
                        "StylistScreenName": "@FadeMasterMike",
                        "RequestedDate": "05/03/2024",
                        "Gap": 60
                        }'




                        *************** RESPONSES ***************




                        200 - OK
                        [
                        {
                        "StylistScreenName": "@FadeMasterMike",
                        "RequestedDate": "5/3/2024",
                        "TimeSlot": "15:30",
                        "Gap": "60",
                        "IsAvailable": true,
                        "IsStartTimeEligible": true,
                        "ReasonNotAvailable": null
                        },
                        {
                        "StylistScreenName": "@FadeMasterMike",
                        "RequestedDate": "5/3/2024",
                        "TimeSlot": "16:00",
                        "Gap": "60",
                        "IsAvailable": true,
                        "IsStartTimeEligible": false,
                        "ReasonNotAvailable": null
                        },
                        {
                        "StylistScreenName": "@FadeMasterMike",
                        "RequestedDate": "5/3/2024",
                        "TimeSlot": "16:30",
                        "Gap": "60",
                        "IsAvailable": false,
                        "IsStartTimeEligible": false,
                        "ReasonNotAvailable": "Timeslot Taken"
                        }
                        ]

                        400 - Bad Request
                        {
                        "Response": "Missing or invalid RequestedDate."
                        }

                        400 - Bad Request
                        {
                        "Response": "Missing or invalid StylistScreenName."
                        }

                        400 - Bad Request
                        {
                        "Response": "Missing or invalid Gap."
                        }

                        401 - Unauthorized
                        {
                        "Response": "Invalid RapidApiKey or ShopKey."
                        }

                        500 - Internal Server Error
                        {
                        "Response": "Internal server error. Please try again later."
                        }
                    
            

In this case, only 15:30 is eligible to be the start of a 60-minute appointment. Although 16:00 is technically available, there is no 30-minute availability after it, so the full appointment can't fit.

This logic helps clients build more intelligent schedulers and avoid presenting options that look valid but would ultimately fail.