> ## 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 appointments and rewards

> Understand customer matching, end-plus-15-minute attendance earning and one-time Acuity reward codes.

Acuity supplies the appointment lifecycle. Perkstar matches the booking to an
existing member, records attendance and controls the linked loyalty balance and
reward state.

## Match the existing member

Perkstar does not create customers or card enrolments from Acuity bookings.
Matching happens when attendance is due, in this order:

1. Find one active Perkstar customer by an exact, case-insensitive email match.
2. If email does not resolve one customer, normalise the Acuity phone number
   using the business country and find one customer by phone.
3. Confirm that customer already has an active enrolment on the linked Stamp
   card.

A name is stored only to help staff recognise the booking. It is never used to
match a customer. An ambiguous email or phone, an unmatched contact, or a
customer who has not joined the linked card does not earn.

<Warning>
  Ask the customer to join the correct Perkstar card before the appointment. An
  unmatched or not-enrolled attendance is not credited retrospectively, and
  Perkstar does not turn the Acuity contact into a new loyalty member.
</Warning>

## Appointment updates and attendance

Perkstar maintains one signed `appointment.changed` subscription because
[Acuity defines it as the catch-all event](https://developers.acuityscheduling.com/docs/webhooks)
for scheduling, rescheduling, cancellation and detail changes. A daily
reconciliation reads the relevant appointment window again to close gaps after
a disabled webhook, provider error or deployment.

Confirmed appointments are auto-marked attended after the **scheduled end plus
15 minutes**. Perkstar uses a deterministic attendance reference, so webhook
retries, the daily reconciliation and repeated processing cannot credit the
same appointment twice.

## How earning is calculated

| Stamp card rule | Acuity attendance result                                                          |
| --------------- | --------------------------------------------------------------------------------- |
| Visit-based     | Awards the card's configured stamps per visit                                     |
| Spend-based     | Applies the card's spend threshold and stamps using the Acuity appointment price  |
| Manual          | Does not earn automatically because the booking has no staff-entered stamp amount |

Spend-based earning requires the same currency in Acuity and Perkstar and a
usable appointment price. A missing price does not invent a spend amount.

<Info>
  Acuity's `paid` indicator is recorded for context but is not an attendance
  gate. A reserved or unpaid appointment can earn after attendance. Acuity
  states that [payment-processor refunds are not reflected in
  Acuity](https://help.acuityscheduling.com/hc/en-us/articles/28052155599885-Handling-refunds-and-price-adjustments),
  so they are not synchronised into Perkstar; use an Acuity cancellation or
  no-show when attendance should be corrected.
</Info>

<Warning>
  When Square routes earning to this same Stamp card, Square is the earning
  owner, including while its connection temporarily needs reconnection. Acuity
  still shows the appointment and can issue or reconcile reward codes, but it
  skips attendance credit. Do not switch an established card's owner while
  appointment or payment events may still be in flight.
</Warning>

## Issue a one-time reward code

Perkstar can provision codes for:

* the normal completed-card reward;
* a configured reward at a particular stamp milestone; and
* the card's birthday reward, when it issues a reward rather than extra stamps.

<Steps>
  <Step title="The customer earns a mapped reward">
    Perkstar confirms the reward is available on the linked card and selects the
    Acuity coupon, package, gift or subscription source mapped to that reward.
  </Step>

  <Step title="Perkstar creates a unique certificate">
    The generated code is attached to that one Perkstar reward. Acuity applies
    the source's service restrictions, value, usage and expiry.
  </Step>

  <Step title="The customer receives the code">
    Perkstar adds the code to the Wallet pass and sends the reward email when a
    deliverable customer email is available. A configured booking button opens
    Acuity with the code and customer booking details prefilled.
  </Step>

  <Step title="The customer books with the code">
    The customer applies it in Acuity's package, gift or coupon field. Acuity
    permits one coupon or package-style code per appointment.
  </Step>

  <Step title="Perkstar records redemption">
    When the appointment reports the managed code, Perkstar claims that exact
    reward once, removes the code from Wallet and queues the Wallet update.
  </Step>
</Steps>

<Note>
  An unavailable or suppressed email does not make the reward disappear. Check
  the customer's current Wallet pass. If the reward should also be emailed,
  correct the customer email and follow the integration's retry guidance.
</Note>

## What is retained

Perkstar retains the provider appointment reference, schedule and duration,
service and calendar/staff labels, appointment price and paid indicator,
cancellation or no-show state, customer contact fields needed for matching,
and whether a managed certificate was applied. Acuity intake-form answers,
internal notes, payment card details and payment-processor transactions are not
retained for this integration.

For corrections and delayed activity, continue to
[Cancellations and troubleshooting](/integrations/acuity/cancellations-troubleshooting).


## Related topics

- [Acuity Scheduling](/integrations/acuity/index.md)
- [Set up Acuity](/integrations/acuity/setup.md)
- [Acuity cancellations and troubleshooting](/integrations/acuity/cancellations-troubleshooting.md)
- [Integration gallery](/integrations/index.md)
- [Webhook event catalogue](/reference/webhook-events.md)