> ## 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 an active Acuity account. Acuity documents that
[its API access requirements](https://help.acuityscheduling.com/hc/en-us/articles/16676949253389-Using-custom-CSS-and-APIs).
Its **Premium or Powerhouse** plans include access to API credentials. If
Perkstar asks for your webhook signing key, confirm that **View credentials**
is available for the authorising user before changing any subscription.
OAuth authorisation and access to that credentials screen are separate checks;
a Connect button alone does not confirm either one.
* 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.
### Direct links to Acuity
Sign in to **your own Acuity account** and check the business before making
changes. These links contain no account, owner or coupon ID;
Acuity opens them using your own login. Keep Perkstar open in another browser
tab so you can return to finish setup. If Acuity asks you to sign in first,
finish signing in and open the required link again.
* [Create an appointment coupon](https://secure.acuityscheduling.com/products.php?action=editCoupon\&apptCoupon=1)
* [Open your appointment coupons](https://secure.acuityscheduling.com/products.php?action=coupons\&apptCoupon=1)
* [Open Acuity Integrations / API](https://secure.acuityscheduling.com/preferences.php?action=integrations)
* [Acuity's illustrated coupon help](https://help.acuityscheduling.com/hc/en-us/articles/16676933307789-Creating-coupons-for-appointments-and-packages-in-Acuity-Scheduling)
— public help, with no Acuity account login required.
## 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.
A manual earning rule does not credit appointments automatically. Perkstar
cannot infer how many stamps a staff member intended to enter.
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.
## Connect and verify booking updates
In Perkstar, open **Integrations → Marketplace**. On a phone, use Safari or
Chrome, tap the menu button at the top right, then **Integrations →
Marketplace**. Use the browser, not the Acuity admin app, for this setup.
Find **Acuity Scheduling** and choose **Connect** on Overview or Setup. This
opens the guided management page; choose **Continue to Acuity** to
authorise. Before the first connection, Setup should show **Not started**.
You do not need to register a developer application or ask Perkstar support
to perform the normal connection.
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.
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.
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.
Select the prepared card under **Choose the programme credited after
attendance** (called **Link your stamp card** in the older settings view).
The selection saves automatically and is applied to open, uncredited Acuity
bookings where safe.
Connecting authorises account access; it does not by itself turn on attendance
earning. Complete **Booking updates** and **Loyalty programme**, then run a test.
The third stage, **Reward codes**, is **required for redemption during Acuity
booking** and is counted separately from attendance earning. Skip it only if
rewards will be redeemed in person. A cancelled or failed authorisation shows a message on the
management page explaining how to continue.
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.
## Configure online reward codes
**Complete this stage if customers should use rewards at Acuity checkout.**
Customers can still earn attendance stamps with online reward codes off, but
must redeem those rewards in person instead.
You create the coupon or package that defines the reward in Acuity first.
Perkstar does **not** create that discount or decide its value and eligible
services for you. After you link it below, Perkstar automatically creates each
customer's unique code when they earn the mapped reward. You do not need to
create a separate coupon manually for every customer.
For an appointment discount or free service, open **Appointment Types →
Coupons → New Coupon for Appointments** in Acuity. Choose the discount,
eligible appointment types and expiry. For a single-use reward, set the
**Total number of uses...** to **1 total use**, not unlimited or once per
client email.
Keep the original setup code private; customers receive their own codes
from Perkstar. You can do this in a mobile browser or Acuity's admin app.
Alternatively, create an appointment package, gift or subscription with the
intended reward entitlement. Use separate sources when completed-card,
milestone or birthday rewards have different terms. Test the generated
code's actual usage limits in Acuity. A
unique generated code does not by itself make an unlimited-use source
single-use.
Under **Let customers use rewards when booking**, enable **Online Acuity
reward codes** and add the business's HTTPS Acuity booking page.
For every reward you want available online, choose **Coupon or discount** or
**Package, gift or subscription**, then enter its numeric Acuity reward
number from its edit page in **Acuity ID**, not the text of a discount code.
For a coupon, copy the digits after `id=` in its browser address. On a
phone, tap the address bar to see the full address.
Leave a row blank
when that reward should remain in-person only.
Choose **Save reward setup**. If customers already have eligible unclaimed
rewards, use **Create waiting codes** after the mappings are saved.
The customer-facing label is **Acuity coupon code**. This is different from
the numeric **Acuity ID** you copied from the coupon edit-page URL during setup.
Customers enter their Acuity coupon code in **Package, gift, or coupon code** at
Acuity checkout. Test an earned code against the intended service before going
live; check its discount and that it cannot be used a second time. Percentage
coupons can include add-ons, and a required deposit may still be payable, so
confirm the booking total rather than assuming every free-service reward makes
every booking free.
### What can be automated?
Perkstar already automates the repeated work: creating an individual Acuity code
when a mapped reward is earned and keeping the reward's redemption status in
sync. The business creates and links the underlying offer once per reward type.
Acuity's documented [certificate creation API](https://developers.acuityscheduling.com/reference/post-certificates)
requires an existing coupon or package ID. Its public API documentation does
not provide an endpoint for creating the underlying discount or package. The
standard Perkstar connection therefore does not create those offers for you.
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).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.