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

# Set up Acuity

> Authorise the complete Acuity account, verify booking updates, link an existing Stamp card and test attendance and reward codes.

Complete these steps before relying on automatic attendance earning. Perkstar
keeps appointment sync, attendance earning and online reward codes as separate
setup stages so each can be verified safely.

## Before you connect

* Use Perkstar Growth or higher.
* Use Acuity Premium or Powerhouse. Acuity documents that
  [API access is available on those plans](https://help.acuityscheduling.com/hc/en-us/articles/16676949253389-Using-custom-CSS-and-APIs).
* Sign in to Perkstar as an owner or manager who can edit operations.
* Ask the Acuity owner or a **Scheduling Administrator** to authorise Perkstar.
  Acuity's lower contributor levels can be limited to selected calendars; see
  [Acuity access levels](https://help.acuityscheduling.com/hc/en-us/articles/16676924963341-Inviting-contributors-to-Acuity-Scheduling).
* Confirm that you are connecting the intended Acuity account. Perkstar
  supports one Acuity account per business.

## Prepare the Stamp card

The card picker shows unarchived **active or draft Stamp cards**. Points,
Cashback and other card types are not eligible.

Before going live, confirm that:

* test earning on a draft if useful, then activate the card before serving
  customers;
* the customers you want to reward already exist in Perkstar and are already
  enrolled on this card;
* an automatic visit or spend rule is configured;
* Acuity and Perkstar use the same currency if the card earns by spend; and
* the expected final, milestone and birthday rewards exist on the card.

<Info>
  A manual earning rule does not credit appointments automatically. Perkstar
  cannot infer how many stamps a staff member intended to enter.
</Info>

<Warning>
  Check whether this card is also routed to Square. If it is, Square remains the
  earning owner, including while its connection temporarily needs reconnection,
  and Acuity will not award attendance a second time. Keep the owner stable
  while appointment or payment events may still be in flight. Use a new card or
  contact support before switching an established card between providers.
</Warning>

## Connect and verify booking updates

<Steps>
  <Step title="Open the Acuity connection">
    In Perkstar, open **Settings → Integrations**, find **Acuity Scheduling**
    and choose **Connect**.
  </Step>

  <Step title="Authorise the complete account">
    Sign in to the correct Acuity account as its owner or Scheduling
    Administrator and approve Perkstar's API access. On return, check the
    displayed Acuity account, timezone and currency.
  </Step>

  <Step title="Verify the Acuity API key if asked">
    Acuity signs a dynamic webhook with the API key belonging to the user who
    authorised it. In Acuity, open **Integrations**, scroll to **API**, choose
    **View credentials**, and copy the API key for that same user. Paste it in
    Perkstar. Perkstar verifies the user ID and key with Acuity before saving it
    securely.
  </Step>

  <Step title="Confirm booking updates">
    Perkstar automatically maintains one catch-all `appointment.changed`
    webhook. Do not add a Perkstar webhook manually in Acuity. The integration
    should report that booking updates are connected.
  </Step>

  <Step title="Choose the Stamp card">
    Select the prepared card under **Link your stamp card**. The selection saves
    automatically and is applied to open, uncredited Acuity bookings where safe.
  </Step>
</Steps>

<Warning>
  Changing the linked Stamp card turns Acuity reward codes off and clears the
  previous card's reward-source mappings. Reconfigure the online rewards step
  before issuing codes from the new card.
</Warning>

## Configure online reward codes

This stage is optional. Customers can still earn attendance stamps when online
reward codes are off.

<Steps>
  <Step title="Create the reusable sources in Acuity">
    Create the coupon or the package, gift or subscription that represents each
    Perkstar reward. Acuity controls its value, eligible services, usage and
    expiry. Use separate sources when completed-card, milestone or birthday
    rewards have different terms.
  </Step>

  <Step title="Turn on Acuity codes in Perkstar">
    Under **Let customers use rewards when booking**, enable **Use Acuity codes
    for rewards** and add the business's HTTPS Acuity booking page.
  </Step>

  <Step title="Match each reward">
    For every reward you want available online, choose **Coupon or discount** or
    **Package, gift or subscription**, then enter its numeric Acuity reward
    number. Leave a row blank when that reward should remain in-person only.
  </Step>

  <Step title="Create codes for existing rewards">
    Save the settings. If customers already have eligible unclaimed rewards, use
    **Create existing codes** after the mappings are saved.
  </Step>
</Steps>

Acuity explains how to [create appointment coupons](https://help.acuityscheduling.com/hc/en-us/articles/16676933307789-Creating-coupons-for-appointments-and-packages-in-Acuity-Scheduling)
and how customers [use package, gift and subscription codes](https://help.acuityscheduling.com/hc/en-us/articles/29268134579085-Redeeming-package-gift-certificate-or-subscription-codes).

## Customer information

Perkstar reads only the account and appointment fields required to display and
reconcile bookings, match an existing customer and operate a reward code. It
does not retain intake-form answers or internal appointment notes. When a
reward code is created, Perkstar sends Acuity the configured source, generated
code and the customer's email where available. A configured booking link can
prefill the code and the customer's booking details.

The business must tell customers about this provider connection and have an
appropriate lawful basis for the data exchange.

* [Perkstar privacy policy](https://dashboard.perkstar.co.uk/privacy)
* [Integration recipients](https://dashboard.perkstar.co.uk/dpa/sub-processors)

## Test before going live

Use a synthetic customer who already exists in Perkstar and is enrolled on the
linked active Stamp card.

1. Book an Acuity appointment using the same email address and confirm it
   appears in Perkstar **Bookings**.
2. Reschedule it and confirm its service time changes without creating a
   duplicate booking.
3. Let a short appointment reach its end time, wait at least 15 minutes and
   confirm the exact visit- or spend-based stamp credit appears once.
4. Repeat with phone matching in a different display format and confirm the
   normalised number resolves the same enrolled customer.
5. Confirm that a name-only, unmatched or not-enrolled booking does not earn
   and does not create a customer or enrolment.
6. Earn one configured reward and confirm the email where deliverable, Wallet
   reward and one-time Acuity code.
7. Book with the code and confirm Perkstar records one redemption and removes
   the used code from Wallet.
8. Cancel one code booking normally and confirm the reward is restored. Mark a
   separate code booking as a no-show and confirm its code remains consumed.

Continue with [Appointments and rewards](/integrations/acuity/appointments-rewards).


## Related topics

- [Acuity Scheduling](/integrations/acuity/index.md)
- [Set up Loyverse](/integrations/loyverse/setup.md)
- [Set up Square](/integrations/square/setup.md)
- [Acuity appointments and rewards](/integrations/acuity/appointments-rewards.md)
- [Acuity cancellations and troubleshooting](/integrations/acuity/cancellations-troubleshooting.md)