# Bookings

Monitor new bookings and automatically update booking statuses through Zapier workflows.

## List bookings

> Get a list of your bookings, sorted by most recently updated first.\
> \
> \*\*Common uses\*\*:\
> \- Trigger a Slack notification when a new booking is created\
> \- Send booking details to a Google Sheet\
> \- Sync bookings to your CRM\
> \
> Use the \`status\` filter to get only bookings with a specific status (like PENDING or APPROVED). Use \`updatedSince\` to get only bookings created or modified after a certain date.\
> \
> \*\*Note\*\*: Include \`page=1\` in your requests for proper pagination.

```json
{"openapi":"3.1.0","info":{"title":"FlowBookings Zapier Integration API","version":"2.0.0"},"tags":[{"name":"Bookings","description":"Monitor new bookings and automatically update booking statuses through Zapier workflows."}],"servers":[{"url":"https://api.flowbookings.io"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your FlowBookings API key. Generate one from Dashboard → Settings → Integrations → API Key. Include this header in every request."}},"parameters":{"PageParam":{"name":"page","in":"query","description":"Page number (starts at 1).","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"LimitParam":{"name":"limit","in":"query","description":"Number of items per page (1-100). Default is 25.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"UpdatedSinceParam":{"name":"updatedSince","in":"query","description":"Only return items created or updated after this date/time (ISO 8601 format).","required":false,"schema":{"type":"string","format":"date-time"}}},"schemas":{"BookingStatus":{"type":"string","enum":["APPROVED","PENDING","CANCELED","NO_SHOW","REJECTED","COMPLETED"],"description":"The current status of a booking.\n\n| Status | What it means |\n|---|---|\n| `PENDING` | Customer has booked but awaiting your approval |\n| `APPROVED` | Booking is confirmed |\n| `CANCELED` | Booking was canceled by you or the customer |\n| `REJECTED` | You declined the booking request |\n| `NO_SHOW` | Customer didn't show up for the appointment |\n| `COMPLETED` | Service was successfully delivered |\n\n**Note**: Once a booking is canceled, rejected, or completed, it cannot be changed to another status."},"PaginatedBookingsResponse":{"type":"object","description":"List of bookings with pagination info.","required":["data","pagination"],"properties":{"data":{"type":"array","description":"Bookings for the current page, sorted by most recently updated first.","items":{"$ref":"#/components/schemas/Booking"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Booking":{"type":"object","description":"A scheduled appointment with a customer.","required":["_id","id","startDate","endDate","status","createdAt","updatedAt"],"properties":{"_id":{"type":"string","description":"Unique booking identifier."},"id":{"type":"string","description":"Booking ID (same as _id)."},"startDate":{"type":"string","format":"date-time","description":"When the appointment starts (UTC time)."},"endDate":{"type":"string","format":"date-time","description":"When the appointment ends (UTC time)."},"status":{"$ref":"#/components/schemas/BookingStatus"},"service":{"$ref":"#/components/schemas/EmbeddedService"},"customer":{"$ref":"#/components/schemas/EmbeddedCustomer"},"price":{"type":"number","format":"float","description":"Price charged for this booking.","minimum":0},"bookedCapacity":{"type":"integer","description":"Number of spots reserved.","minimum":1},"additionalData":{"type":"string","description":"Custom form data submitted by the customer (JSON format)."},"internalNote":{"type":"string","description":"Your private notes about this booking (not visible to customers)."},"createdAt":{"type":"string","format":"date-time","description":"When the booking was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the booking was last updated."}}},"EmbeddedService":{"type":"object","description":"Service information for this booking.","required":["_id","name"],"properties":{"_id":{"type":"string","description":"Unique service identifier."},"name":{"type":"string","description":"Service name."}}},"EmbeddedCustomer":{"type":"object","description":"Customer information for this booking.","required":["_id"],"properties":{"_id":{"type":"string","description":"Unique customer identifier."},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"email":{"type":"string","format":"email","description":"Email address."}}},"Pagination":{"type":"object","description":"Information about the current page of results.","required":["page","limit","hasMore"],"properties":{"page":{"type":"integer","minimum":1,"description":"Current page number."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum items per page."},"hasMore":{"type":"boolean","description":"True if more pages are available."}}},"Error":{"type":"object","description":"Error information.","required":["error","messages"],"properties":{"error":{"type":"string","description":"Error type.","enum":["unauthorized","validation_error","not_found","server_error"]},"messages":{"type":"array","description":"Details about what went wrong.","items":{"type":"string"},"minItems":1}}}},"responses":{"Unauthorized":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Something went wrong on our end. Please try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/zapier/bookings":{"get":{"tags":["Bookings"],"operationId":"listBookings","summary":"List bookings","description":"Get a list of your bookings, sorted by most recently updated first.\n\n**Common uses**:\n- Trigger a Slack notification when a new booking is created\n- Send booking details to a Google Sheet\n- Sync bookings to your CRM\n\nUse the `status` filter to get only bookings with a specific status (like PENDING or APPROVED). Use `updatedSince` to get only bookings created or modified after a certain date.\n\n**Note**: Include `page=1` in your requests for proper pagination.","parameters":[{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/UpdatedSinceParam"},{"name":"status","in":"query","description":"Filter bookings by status. Case-insensitive (you can use 'pending' or 'PENDING').\n\nExamples:\n- `PENDING` - Get bookings awaiting approval\n- `APPROVED` - Get confirmed bookings\n- `CANCELED` - Get canceled bookings","required":false,"schema":{"$ref":"#/components/schemas/BookingStatus"}}],"responses":{"200":{"description":"Bookings retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedBookingsResponse"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Get a booking by ID

> Get details for a specific booking.\
> \
> \*\*Common use\*\*: Look up booking information by ID to display details or check status.

```json
{"openapi":"3.1.0","info":{"title":"FlowBookings Zapier Integration API","version":"2.0.0"},"tags":[{"name":"Bookings","description":"Monitor new bookings and automatically update booking statuses through Zapier workflows."}],"servers":[{"url":"https://api.flowbookings.io"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your FlowBookings API key. Generate one from Dashboard → Settings → Integrations → API Key. Include this header in every request."}},"parameters":{"BookingIdParam":{"name":"bookingId","in":"path","description":"The booking ID.","required":true,"schema":{"type":"string"}}},"schemas":{"SingleBookingResponse":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#/components/schemas/Booking"}}},"Booking":{"type":"object","description":"A scheduled appointment with a customer.","required":["_id","id","startDate","endDate","status","createdAt","updatedAt"],"properties":{"_id":{"type":"string","description":"Unique booking identifier."},"id":{"type":"string","description":"Booking ID (same as _id)."},"startDate":{"type":"string","format":"date-time","description":"When the appointment starts (UTC time)."},"endDate":{"type":"string","format":"date-time","description":"When the appointment ends (UTC time)."},"status":{"$ref":"#/components/schemas/BookingStatus"},"service":{"$ref":"#/components/schemas/EmbeddedService"},"customer":{"$ref":"#/components/schemas/EmbeddedCustomer"},"price":{"type":"number","format":"float","description":"Price charged for this booking.","minimum":0},"bookedCapacity":{"type":"integer","description":"Number of spots reserved.","minimum":1},"additionalData":{"type":"string","description":"Custom form data submitted by the customer (JSON format)."},"internalNote":{"type":"string","description":"Your private notes about this booking (not visible to customers)."},"createdAt":{"type":"string","format":"date-time","description":"When the booking was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the booking was last updated."}}},"BookingStatus":{"type":"string","enum":["APPROVED","PENDING","CANCELED","NO_SHOW","REJECTED","COMPLETED"],"description":"The current status of a booking.\n\n| Status | What it means |\n|---|---|\n| `PENDING` | Customer has booked but awaiting your approval |\n| `APPROVED` | Booking is confirmed |\n| `CANCELED` | Booking was canceled by you or the customer |\n| `REJECTED` | You declined the booking request |\n| `NO_SHOW` | Customer didn't show up for the appointment |\n| `COMPLETED` | Service was successfully delivered |\n\n**Note**: Once a booking is canceled, rejected, or completed, it cannot be changed to another status."},"EmbeddedService":{"type":"object","description":"Service information for this booking.","required":["_id","name"],"properties":{"_id":{"type":"string","description":"Unique service identifier."},"name":{"type":"string","description":"Service name."}}},"EmbeddedCustomer":{"type":"object","description":"Customer information for this booking.","required":["_id"],"properties":{"_id":{"type":"string","description":"Unique customer identifier."},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"email":{"type":"string","format":"email","description":"Email address."}}},"Error":{"type":"object","description":"Error information.","required":["error","messages"],"properties":{"error":{"type":"string","description":"Error type.","enum":["unauthorized","validation_error","not_found","server_error"]},"messages":{"type":"array","description":"Details about what went wrong.","items":{"type":"string"},"minItems":1}}}},"responses":{"Unauthorized":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested item was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Something went wrong on our end. Please try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/zapier/bookings/{bookingId}":{"get":{"tags":["Bookings"],"operationId":"getBooking","summary":"Get a booking by ID","description":"Get details for a specific booking.\n\n**Common use**: Look up booking information by ID to display details or check status.","parameters":[{"$ref":"#/components/parameters/BookingIdParam"}],"responses":{"200":{"description":"Booking retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleBookingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```

## Update booking status

> Change a booking's status (approve, cancel, mark complete, etc.).\
> \
> \*\*Common uses\*\*:\
> \- Automatically approve bookings when payment is received in Stripe\
> \- Cancel bookings when a refund is issued\
> \- Mark bookings complete when service is delivered\
> \- Set no-show status when customer doesn't attend\
> \
> \*\*Important\*\*: You cannot change the status of bookings that are already canceled, rejected, or completed.

```json
{"openapi":"3.1.0","info":{"title":"FlowBookings Zapier Integration API","version":"2.0.0"},"tags":[{"name":"Bookings","description":"Monitor new bookings and automatically update booking statuses through Zapier workflows."}],"servers":[{"url":"https://api.flowbookings.io"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your FlowBookings API key. Generate one from Dashboard → Settings → Integrations → API Key. Include this header in every request."}},"parameters":{"BookingIdParam":{"name":"bookingId","in":"path","description":"The booking ID.","required":true,"schema":{"type":"string"}}},"schemas":{"UpdateBookingStatusRequest":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/BookingStatus","description":"The new status for the booking. Case-insensitive (you can use 'approved' or 'APPROVED').\n\n**Note**: You cannot change the status of bookings that are already canceled, rejected, or completed."}}},"BookingStatus":{"type":"string","enum":["APPROVED","PENDING","CANCELED","NO_SHOW","REJECTED","COMPLETED"],"description":"The current status of a booking.\n\n| Status | What it means |\n|---|---|\n| `PENDING` | Customer has booked but awaiting your approval |\n| `APPROVED` | Booking is confirmed |\n| `CANCELED` | Booking was canceled by you or the customer |\n| `REJECTED` | You declined the booking request |\n| `NO_SHOW` | Customer didn't show up for the appointment |\n| `COMPLETED` | Service was successfully delivered |\n\n**Note**: Once a booking is canceled, rejected, or completed, it cannot be changed to another status."},"SingleBookingResponse":{"type":"object","required":["booking"],"properties":{"booking":{"$ref":"#/components/schemas/Booking"}}},"Booking":{"type":"object","description":"A scheduled appointment with a customer.","required":["_id","id","startDate","endDate","status","createdAt","updatedAt"],"properties":{"_id":{"type":"string","description":"Unique booking identifier."},"id":{"type":"string","description":"Booking ID (same as _id)."},"startDate":{"type":"string","format":"date-time","description":"When the appointment starts (UTC time)."},"endDate":{"type":"string","format":"date-time","description":"When the appointment ends (UTC time)."},"status":{"$ref":"#/components/schemas/BookingStatus"},"service":{"$ref":"#/components/schemas/EmbeddedService"},"customer":{"$ref":"#/components/schemas/EmbeddedCustomer"},"price":{"type":"number","format":"float","description":"Price charged for this booking.","minimum":0},"bookedCapacity":{"type":"integer","description":"Number of spots reserved.","minimum":1},"additionalData":{"type":"string","description":"Custom form data submitted by the customer (JSON format)."},"internalNote":{"type":"string","description":"Your private notes about this booking (not visible to customers)."},"createdAt":{"type":"string","format":"date-time","description":"When the booking was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the booking was last updated."}}},"EmbeddedService":{"type":"object","description":"Service information for this booking.","required":["_id","name"],"properties":{"_id":{"type":"string","description":"Unique service identifier."},"name":{"type":"string","description":"Service name."}}},"EmbeddedCustomer":{"type":"object","description":"Customer information for this booking.","required":["_id"],"properties":{"_id":{"type":"string","description":"Unique customer identifier."},"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"email":{"type":"string","format":"email","description":"Email address."}}},"Error":{"type":"object","description":"Error information.","required":["error","messages"],"properties":{"error":{"type":"string","description":"Error type.","enum":["unauthorized","validation_error","not_found","server_error"]},"messages":{"type":"array","description":"Details about what went wrong.","items":{"type":"string"},"minItems":1}}}},"responses":{"Unauthorized":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested item was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Something went wrong on our end. Please try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/zapier/bookings/{bookingId}":{"put":{"tags":["Bookings"],"operationId":"updateBookingStatus","summary":"Update booking status","description":"Change a booking's status (approve, cancel, mark complete, etc.).\n\n**Common uses**:\n- Automatically approve bookings when payment is received in Stripe\n- Cancel bookings when a refund is issued\n- Mark bookings complete when service is delivered\n- Set no-show status when customer doesn't attend\n\n**Important**: You cannot change the status of bookings that are already canceled, rejected, or completed.","parameters":[{"$ref":"#/components/parameters/BookingIdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBookingStatusRequest"}}}},"responses":{"200":{"description":"Status updated successfully. Returns the full updated booking.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleBookingResponse"}}}},"400":{"description":"Invalid status value or booking cannot be updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```