> ## 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 Scheduling

> Connect Acuity appointments to an existing Perkstar Stamp card for attendance earning and one-time online reward codes.

<Icon icon="calendar-check" size={36} />

Use Acuity Scheduling as the appointment system while Perkstar remains the
loyalty system of record. Appointments sync into **Bookings**, eligible
attendance credits an existing Stamp card enrolment, and configured rewards
receive a one-time Acuity code for online booking.

<CardGroup cols={3}>
  <Card title="Match" icon="user-check">
    Match one existing Perkstar customer and card enrolment by email or
    normalised phone number. Names are never used for matching.
  </Card>

  <Card title="Attend" icon="calendar-check">
    Mark a confirmed appointment attended after its end time plus 15 minutes and
    apply the linked card's visit or spend rule once.
  </Card>

  <Card title="Reward" icon="gift">
    Create a unique Acuity certificate for a completed-card, milestone or
    birthday reward and keep the code on the customer's Wallet pass.
  </Card>
</CardGroup>

## System boundaries

| Event or responsibility                                      | System of record                | Result                                                                               |
| ------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------ |
| Appointment schedule, service, calendar and status           | Acuity                          | Perkstar keeps the fields required to show and reconcile the booking                 |
| Loyalty membership, stamps, rewards and Wallet pass          | Perkstar                        | An eligible attended appointment credits the existing enrolment once                 |
| Coupon, package, gift or subscription value and restrictions | Acuity                          | Perkstar creates a unique code against the configured Acuity source                  |
| Appointment payment and payment-processor refund             | Acuity or its payment processor | Perkstar does not use payment status as an attendance gate and does not sync refunds |
| Normal cancellation or no-show                               | Acuity                          | Perkstar applies the supported loyalty and certificate correction once               |

<Warning>
  Acuity is an **attendance integration, not a payment-settlement integration**.
  A paid flag is not required for attendance earning, and an Acuity or
  payment-processor refund does not reverse loyalty. Record a normal
  cancellation or no-show in Acuity when the appointment outcome changes.
</Warning>

## Important boundaries

* Acuity supports **Stamp cards only**. Points, Cashback and other card types
  are not available for this connection.
* One Acuity account and one Stamp card can be linked to a Perkstar business.
  The same route applies across that Acuity account's calendars, staff and
  appointment types.
* The customer must already exist in Perkstar and already be enrolled on the
  linked card. Acuity bookings never create a customer or a card enrolment.
* Matching uses a unique case-insensitive email first, then a normalised phone
  number. A name alone never matches.
* Visit rules use the configured stamps per visit. Spend rules use the Acuity
  appointment price and require matching Acuity and Perkstar currencies.
  Manual earning rules do not award automatically.

<Warning>
  If the same Stamp card is routed to Square, **Square owns earning**, including
  while that connection temporarily needs reconnection. Acuity continues to sync
  appointments and provide configured reward codes, but does not add a second
  credit. Keep that ownership stable while appointment or payment events may
  still be in flight; use a new card or contact support for a clean cutover.
</Warning>

## What you need

* A Perkstar **Growth** plan or higher.
* An Acuity **Premium or Powerhouse** plan, which provides API access.
* Perkstar owner or manager access with permission to edit operations.
* The Acuity account owner or a **Scheduling Administrator** to authorise the
  connection. Lower contributor levels can be limited to selected calendars.
* One unarchived active or draft Stamp card. A draft can award stamps during a
  controlled test; activate it before serving customers.
* Existing Perkstar customers already enrolled on that card.
* The same business currency in Acuity and Perkstar if the card earns by spend.

<CardGroup cols={3}>
  <Card title="Set up Acuity" icon="sliders" href="/integrations/acuity/setup">
    Authorise the complete account, verify booking updates, link the card and
    test the full journey.
  </Card>

  <Card title="Appointments and rewards" icon="calendar-check" href="/integrations/acuity/appointments-rewards">
    Understand matching, attendance earning and the customer reward-code flow.
  </Card>

  <Card title="Cancellations and help" icon="life-ring" href="/integrations/acuity/cancellations-troubleshooting">
    Correct cancellations and no-shows, diagnose missing activity and disconnect
    safely.
  </Card>
</CardGroup>

## Data flow

| Direction           | Information                                                                                                                                                                                                                    | Purpose                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Acuity → Perkstar   | Account identity and currency; appointment reference, times, duration, service, calendar/staff label, price, paid indicator, cancellation/no-show state, customer name, email and phone, and whether a certificate was applied | Display and reconcile the booking, match an existing customer, calculate attendance earning and detect a managed code |
| Perkstar → Acuity   | One managed `appointment.changed` webhook subscription; generated certificate code, configured source ID and customer email where available                                                                                    | Receive appointment changes and create the customer's one-time reward code                                            |
| Perkstar → customer | Reward email where deliverable, booking link and updated Apple Wallet or Google Wallet pass                                                                                                                                    | Let the customer use and track the reward                                                                             |

Perkstar retains only the appointment fields required for this workflow. It
does not retain Acuity intake-form answers, internal appointment notes, payment
card details or payment-processor transactions.

<Note>
  Need help with a connection? Email
  [support@perkstar.co.uk](mailto:support@perkstar.co.uk) with the Perkstar
  business name, Acuity appointment number and approximate time. Never send an
  API key, access token, customer intake-form answer or full webhook payload.
</Note>


## Related topics

- [Acuity Scheduling](/integrations/acuity/index.md)
- [Set up Acuity](/integrations/acuity/setup.md)
- [Integration gallery](/integrations/index.md)
- [Acuity cancellations and troubleshooting](/integrations/acuity/cancellations-troubleshooting.md)
- [Acuity appointments and rewards](/integrations/acuity/appointments-rewards.md)