Bookings

Creating a booking

Create a booking by sending a POST request to /v1/bookings. This is a public endpoint — no authentication required, so your end users can book directly.

curl -X POST https://api.astrocal.dev/v1/bookings \
  -H "Content-Type: application/json" \
  -d '{
    "event_type_id": "evt_abc123",
    "start_time": "2026-03-15T14:00:00Z",
    "invitee_name": "Jane Doe",
    "invitee_email": "jane@example.com",
    "invitee_timezone": "America/Los_Angeles"
  }'

The API validates the requested slot against availability rules and existing bookings. If the slot is unavailable, you'll get a 409 Conflict response.

The response includes a cancel_token that enables self-service cancellation and rescheduling without authentication.

Cancelling a booking

Cancel a booking by sending a POST request to /v1/bookings/{id}/cancel.

With a cancel token (invitee self-service)

The cancel token is included in the booking response and in confirmation emails. Invitees can cancel without logging in:

curl -X POST "https://api.astrocal.dev/v1/bookings/bk_123/cancel?token=abc123" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Schedule conflict"}'

With an API key (developer)

Developers can cancel any booking in their organization using an API key:

curl -X POST https://api.astrocal.dev/v1/bookings/bk_123/cancel \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer requested cancellation"}'

Cancellation behavior

• The booking status changes to cancelled and cancelled_at is set.
• The Google Calendar event is deleted automatically.
• Cancellation emails are sent to both the invitee and organizer.
• A booking.cancelled webhook event is dispatched.
• Cancellation is idempotent — cancelling an already-cancelled booking returns success.

Rescheduling a booking

Reschedule a booking by sending a POST request to /v1/bookings/{id}/reschedule with the new start time.

With a cancel token (invitee self-service)

curl -X POST "https://api.astrocal.dev/v1/bookings/bk_123/reschedule?token=abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "new_start_time": "2026-03-16T10:00:00Z",
    "reason": "Need to move to Tuesday"
  }'

With an API key (developer)

curl -X POST https://api.astrocal.dev/v1/bookings/bk_123/reschedule \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{"new_start_time": "2026-03-16T10:00:00Z"}'

Reschedule behavior

• The new time slot is validated against availability rules and existing bookings. The current booking's slot is excluded from conflict checking (since it's being replaced).
• The booking's start_time and end_time are updated. The booking ID and cancel token remain the same.
• The Google Calendar event is updated with the new times.
• Reschedule emails with an updated .ics attachment are sent to both parties.
• A booking.rescheduled webhook event is dispatched.
• You cannot reschedule a cancelled booking — you'll get a 409 Conflict.
• The new_start_time must be in the future — past times return a 422 error.

Listing bookings

List bookings for your organization with optional filters:

curl https://api.astrocal.dev/v1/bookings?status=confirmed&limit=10 \
  -H "Authorization: Bearer ac_live_..."

Supports filtering by event_type_id, status, start_date, and end_date. Uses cursor-based pagination with starting_after.

Authentication summary