> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Acuity cancellations and troubleshooting

> Correct cancellations and no-shows, diagnose missing attendance or reward codes and disconnect Acuity safely.

## Cancellations and no-shows

Record the real appointment outcome in Acuity. Perkstar reads the resulting
appointment state through the managed webhook or daily reconciliation and
applies the supported correction idempotently.

| Acuity outcome | Attendance credit | Managed reward code |
| - | - | - |
| Normal cancellation before attendance | No credit is added | A code applied to the booking is restored when still eligible |
| Normal cancellation after auto-attendance | The prior attendance credit is reversed | The applied code is restored when still eligible |
| No-show before attendance | No attendance credit is added | The code remains consumed |
| No-show after auto-attendance | The prior attendance credit is reversed | The code remains consumed |

A provider cancellation or no-show remains authoritative even if delivery is
late. Manual attendance corrections in Perkstar are limited to 72 hours.
If the earned value has already been used or later activity makes reversal
unsafe, Perkstar flags the booking for manual review instead of guessing.

<Warning>
  Do not make a manual stamp or reward adjustment while an Acuity correction is
  pending. The managed webhook or daily reconciliation may still apply the
  automatic reversal or restoration, causing a duplicate correction.
</Warning>

An Acuity or payment-processor refund by itself does not change attendance or
reverse stamps. Acuity is the source of the appointment outcome, not payment
settlement.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Acuity is not available to connect">
    New connections require Perkstar Growth or higher and an active Acuity
    account with the required API access. Sign in to Perkstar as an owner or
    manager. The Acuity owner or a Scheduling Administrator should authorise the
    connection so the OAuth user is not restricted to selected calendars.
  </Accordion>

  <Accordion title="Acuity says the trial has expired">
    Check the subscription for the exact Acuity account connected to Perkstar. A
    saved Perkstar connection is not proof that its subscription or public
    scheduler is active. If you have already paid, check the account and invoice
    with Acuity support instead of purchasing again. Acuity documents Premium or
    Powerhouse for API credentials; verify **View credentials** access if
    Perkstar asks for a signing key. Once account access is working, complete a
    real booking-to-reward test before inviting customers to use it.
  </Accordion>

  <Accordion title="The API key is rejected">
    In Acuity, open **Integrations → API → View credentials**. Copy the API key
    belonging to the same Acuity user who authorised Perkstar. Perkstar verifies
    the key and user ID with Acuity before saving it; a key from another user or
    account cannot verify this connection.
  </Accordion>

  <Accordion title="Booking updates need attention">
    Perkstar should maintain one `appointment.changed` subscription. Do not add
    a manual Perkstar webhook. Reconnect or save the verified API key again so
    Perkstar can inspect, remove stale managed subscriptions and restore the
    catch-all subscription. The daily reconciliation remains the recovery path,
    but the warning should still be resolved.
  </Accordion>

  <Accordion title="An appointment is missing from Bookings">
    Confirm it belongs to the connected Acuity account and a calendar visible to
    the user who authorised Perkstar. Check the integration account, timezone
    and last sync. Allow the daily reconciliation to close a transient webhook
    gap before recreating the appointment.
  </Accordion>

  <Accordion title="The appointment ended but no stamps were added">
    Wait until the scheduled end plus 15 minutes. Confirm the linked Stamp card
    is active, the Acuity and Perkstar currencies match for spend earning, and
    no Square route owns earning for the same card. The Acuity contact must
    resolve uniquely by email or normalised phone to an existing Perkstar
    customer who is already enrolled on that card. A name-only match, missing
    enrolment or manual card rule does not earn. Interrupted loyalty writes are
    durably retried by the attendance worker; do not manually add a duplicate
    stamp while recovery is pending. A booking deliberately skipped because the
    customer was not enrolled is not credited retroactively by a duplicate
    delivery after they join.
  </Accordion>

  <Accordion title="A busy account reports an incomplete appointment window">
    Reconciliation splits full results by date and calendar and checks both
    sorted ends of a dense day. If it still cannot prove that all appointments
    were returned, it reports the affected window while continuing other
    windows. Keep signed booking updates connected and contact support with the
    affected dates and calendar numbers; do not treat that sync as complete.
  </Accordion>

  <Accordion title="The appointment is unpaid or was refunded">
    Payment is not the attendance gate. A confirmed appointment can earn after
    its end even when Acuity reports it unpaid. Acuity and processor refunds do
    not sync into loyalty. Mark the appointment cancelled or no-show in Acuity
    when the attendance outcome should reverse the credit.
  </Accordion>

  <Accordion title="A reward row is not shown">
    Final reward appears for the Stamp card's completed-card reward. Milestone
    and birthday rows appear only when those rewards exist on that same card.
    Changing the attendance card disables codes and clears the previous
    card-specific mappings.
  </Accordion>

  <Accordion title="A reward did not receive a code">
    Confirm online reward codes are enabled, the reward is mapped to a whole
    numeric Acuity source ID and the source still exists. Save the mappings,
    then use **Create existing codes** for eligible unclaimed rewards earned
    before setup. A code can remain on Wallet even when email delivery is
    unavailable or suppressed.
  </Accordion>

  <Accordion title="A code is not accepted by Acuity">
    Check the source's expiry, remaining use, eligible appointment types and
    value in Acuity. Only one coupon, package, gift or subscription code can be
    applied to an appointment. Do not replace the Perkstar-generated code with a
    reusable public coupon.
  </Accordion>

  <Accordion title="More than one Acuity account is connected">
    Perkstar pauses automatic work rather than choosing an account. Contact
    [Perkstar support](mailto:support@perkstar.co.uk) to separate the
    connections safely.
  </Accordion>
</AccordionGroup>

## Disconnect safely

<Warning>
  Disconnect in Perkstar **before** revoking Perkstar from Acuity. Working
  Acuity access is required to remove managed certificates and the webhook
  subscription safely.
</Warning>

<Steps>
  <Step title="Resolve pending corrections">
    Allow any displayed cancellation, no-show or certificate cleanup to finish
    and record the affected appointment numbers.
  </Step>

  <Step title="Disconnect in Perkstar">
    Open **Settings → Integrations → Acuity** and choose **Disconnect Acuity**.
    Perkstar first retires managed Acuity certificates and removes its managed
    webhook subscription.
  </Step>

  <Step title="Retry if cleanup is still pending">
    Keep Acuity authorised. If Perkstar reports pending certificate or webhook
    cleanup, wait briefly and choose disconnect again rather than revoking the
    account first.
  </Step>

  <Step title="Remove provider access if wanted">
    Only after Perkstar reports the integration disconnected should you remove
    its access from Acuity.
  </Step>
</Steps>

Disconnecting stops appointment sync and new automatic reward codes. Open
bookings are unlinked from the attendance card, and managed codes are removed
from Wallet as cleanup completes. Existing Perkstar customers, card
enrolments, cards, completed booking records, transaction history and earned
loyalty rewards remain under the normal retention rules.

Already revoked Acuity access first? Do not make replacement loyalty
adjustments. Email [support@perkstar.co.uk](mailto:support@perkstar.co.uk) with
the Perkstar business name and affected appointment numbers so cleanup can be
reviewed without exposing customer contact details or credentials.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.