Cancel Flow

FrontdeQ can cancel Square appointments directly from a phone call. The flow is deliberately strict so cancellations only happen when the caller actually means them.

The Flow

When a caller says they want to cancel:

1. Identify the caller. The AI looks up the caller ID against Square customers. If no match, it asks for the phone number on file.
2. List upcoming bookings. "I see a haircut with Sofia on Tuesday at 2pm, and a color with Maria next Saturday at 11am."
3. Confirm which one. "Which one would you like to cancel?"
4. Get an explicit "yes." "Just to confirm — cancel your Tuesday 2pm with Sofia. Yes?" Waits for an unambiguous confirmation. "Maybe" or "I think so" does not cancel anything.
5. Call cancel_booking. The booking status flips to CANCELLED_BY_SELLER in Square. Square sends the customer a cancellation email automatically.
6. Confirm warmly. "Cancelled. You'll get a confirmation from Square."

One booking per call. If the caller wants to cancel multiple, the AI cancels the first, confirms, then asks if they'd like to cancel another.

Requirements

Two things are required for API cancellation to work:

1. APPOINTMENTS_ALL_WRITE OAuth scope

FrontdeQ needs the seller-level write permission from Square to cancel bookings on your behalf. This was added to the scope list in v0.3.0.0.

If you connected Square before 2026-04-18, you'll need to reconnect once to grant the new scope:

• Go to Settings → Integrations → Connect Square
• Approve the cancellation permission
• Your existing bookings, staff, and customer data stay intact — only the scope is upgraded

Merchants who connected after v0.3.0.0 shipped already have the scope.

2. Square Appointments Plus or Premium

Seller-level bookings.cancel() requires an Appointments Plus or Premium subscription on your Square account (Square's rule, not ours). If you're on the Free tier:

• The AI will still collect cancellation requests — it falls back to the voicemail path (see below)
• Upgrading your Square subscription activates real API cancellation automatically, no code change needed

Check your Square subscription under your Square Dashboard → Settings → Appointments.

Graceful Fallback

The AI handles two cases where Square blocks a cancellation:

Merchant policy / subscription tier. Square returns "Merchant does not allow cancellation." The AI does not tell the caller it failed. It says: "Let me pass that to the team to confirm your cancellation." The take_message tool fires with urgency set based on the appointment timing:

• Within 24 hours: urgency: 'urgent'
• More than 24 hours out: urgency: 'normal'

Staff gets an email with the cancellation request and completes it manually in Square.

Past the cancellation window. Same fallback. Some bookings are too close to their start time to cancel via API. The AI routes to take_message so staff can decide whether to cancel with or without a late-cancel fee.

Either way, the caller's request reaches staff. The experience is seamless — they don't hear "sorry, I can't help with that."

The "Explicit Yes" Rule

The AI will not cancel on:

• "Maybe"
• "I think so"
• "Sure, whatever"
• Silence or filler
• Any response that isn't an unambiguous yes

This is deliberate. The cost of one extra confirmation turn is a few seconds. The cost of a wrong cancellation is a client who shows up to a slot you gave away. We tested a looser version and the latter happened more often than the former was worth.

Testing It

To test the cancellation flow without impacting a real client:

1. Book a test appointment in Square far in the future (e.g., 90 days out)
2. Call your FrontdeQ phone number from the phone number on file
3. Ask to cancel
4. Walk through the flow and confirm
5. Check Square — the booking should show status CANCELLED_BY_SELLER

If the cancellation returns "Merchant does not allow cancellation" even after upgrading your Square subscription and reconnecting with the new scope, contact support with the call_id from the dashboard.

What Staff Sees

Every cancellation (API or take-message fallback) shows up in your dashboard Call Log with:

• Caller name and phone
• Intent: "cancel"
• Tool calls made: search_customer_phone, list_bookings, cancel_booking (or take_message on fallback)
• Outcome: resolved or unresolved
• Full recording and transcript

If a take-message fallback fires, staff also gets the standard voicemail alert email.

Not Yet Supported

• Cancelling multiple bookings in one call. The AI cancels one, asks if there's another, then does the second one in a new exchange. This keeps reasoning simple and reduces accidental multi-cancellation risk.
• Reschedule-instead-of-cancel upsell. The AI doesn't proactively offer to reschedule before cancelling. If the caller explicitly says "actually, can I move it instead?" the reschedule flow kicks in. But the AI won't push rescheduling as a default.
• Cancellation fees. Square handles these on its own, based on your salon's policy. FrontdeQ doesn't quote or collect fees.