> ## 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.
# Triggers, actions, and searches
> The exact operations in the public Perkstar app for Zapier, including event names and safety boundaries.
The public Beta catalogue contains 29 instant triggers, 10 visible actions, two
searches, and two explicit Search-or-Create relationships. Zapier subscribes to
one Perkstar webhook event when the Zap is enabled and deletes that app-managed
subscription when the trigger is disabled or removed.
Open [Perkstar in Zapier's App
Directory](https://zapier.com/apps/perkstar/integrations) to use this
catalogue without an invitation. The app is in public Beta, so event payloads
can gain new optional fields; map only the fields your Zap needs.
## Instant triggers
The integration defines one named Zapier trigger for each real business event below.
The diagnostic `webhook.test` event is deliberately excluded from the Zapier
catalogue.
### Customer lifecycle
| Zapier trigger | Perkstar event | Fires when |
| -------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| New Customer Enrolment | `customer.enrolled` | A customer first joins a loyalty card. |
| Customer Unenrolled | `customer.unenrolled` | Access to a card ends. |
| Customer Anonymised | `customer.anonymized` | Perkstar removes the customer's direct identifiers. |
| Customer Lifecycle Group Changed | `customer.group_changed` | A customer moves between Perkstar's six exclusive lifecycle groups. |
The lifecycle-group trigger does not represent an operator-created saved
segment. Perkstar stores a customer's first classification as a baseline and
does not emit it, preventing a newly connected Zap from receiving every
existing customer.
### Wallet, scanner, expiry, and referrals
| Zapier trigger | Perkstar event | Fires when |
| --------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Wallet Pass Installed | `wallet.installed` | Perkstar first observes an Apple or Google Wallet install; Google observation is periodic rather than immediate. |
| Card Scanned | `card.scanned` | An online Perkstar Scanner lookup successfully resolves a customer card; offline cache-only lookups do not fire. |
| Customer Card Expired | `card.expired` | One enrolment reaches its effective expiry; a later expiry after extension can produce another event. |
| New Customer Referral | `referral.created` | One customer refers another customer to a Perkstar loyalty-card programme. |
`referral.created` is customer-to-customer loyalty activity. It is not a
merchant, agency, or partner-referral event.
The first group-change or Google-install trigger in a business establishes a
no-event baseline on the next completed periodic sweep. Tracking begins after that
warm-up; Apple installs remain callback-driven, and post-subscription expiries
retain their effective expiry time while waiting for projection.
The five trigger records flatten these event fields for later Zap steps:
| Trigger | Event-specific fields |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Customer Lifecycle Group Changed | `customerId`, `previousGroup`, `currentGroup`, `occurredAt` |
| Wallet Pass Installed | `walletPassId`, `enrollmentId`, `customerId`, `cardId`, `platform`, `detectionSource`, `installedAt`, `occurredAt` |
| Card Scanned | `scanId`, `enrollmentId`, `customerId`, `cardId`, `credentialType`, nullable `walletPassId`, nullable `platform`, nullable `locationId`, `occurredAt` |
| Customer Card Expired | `enrollmentId`, `customerId`, `cardId`, `cardType`, `expiresAt`, `expirySource`, `occurredAt` |
| New Customer Referral | `referralId`, `cardId`, `referrerEnrollmentId`, `referrerCustomerId`, `referredEnrollmentId`, `referredCustomerId`, `status`, `bonusTiming`, nullable `creditedAt`, `occurredAt` |
### Loyalty activity
| Zapier trigger | Perkstar event | Fires when |
| ----------------------- | --------------------- | -------------------------------------------------------------------------- |
| New Loyalty Transaction | `transaction.created` | A supported loyalty-ledger row commits, including a compensating reversal. |
| Coupon Redeemed | `coupon.redeemed` | A coupon card is redeemed. |
| Reward Redeemed | `reward.redeemed` | A reward, offer, voucher, or milestone is redeemed. |
| Loyalty Tier Changed | `tier.changed` | A status, cashback, or discount tier changes. |
### Tickets, gifts, and multipasses
| Zapier trigger | Perkstar event | Fires when |
| ------------------- | --------------------- | --------------------------------------------------- |
| Ticket Purchased | `ticket.purchased` | Paid ticket fulfilment completes. |
| Ticket Cancelled | `ticket.cancelled` | A ticket event is cancelled. |
| Ticket Refunded | `ticket.refunded` | A ticket payment is refunded or lost to chargeback. |
| Gift Card Purchased | `gift.purchased` | Paid gift fulfilment completes. |
| Gift Card Redeemed | `gift.redeemed` | Value is spent from a gift card. |
| Multipass Purchased | `multipass.purchased` | A multipass is purchased or topped up. |
### Memberships
| Zapier trigger | Perkstar event | Fires when |
| -------------------- | ---------------------- | --------------------------------------------------------------- |
| Membership Purchased | `membership.purchased` | A recurring or one-off membership first activates. |
| Membership Renewed | `membership.renewed` | A recurring membership advances to a new billing period. |
| Membership Cancelled | `membership.cancelled` | A recurring membership becomes cancelled or incomplete-expired. |
### Engagement
| Zapier trigger | Perkstar event | Fires when |
| ------------------ | -------------------- | -------------------------------------------------------- |
| Feedback Submitted | `feedback.submitted` | A customer submits card feedback. |
| Automation Fired | `automation.fired` | A Perkstar automated-message firing is recorded. |
| Broadcast Sent | `broadcast.sent` | A Wallet broadcast reaches terminal delivery processing. |
### Bookings
| Zapier trigger | Perkstar event | Fires when |
| ------------------------- | ------------------- | ----------------------------------- |
| Booking Created | `booking.created` | A booking is created. |
| Booking Confirmed | `booking.confirmed` | A booking moves to confirmed. |
| Booking Attended | `booking.attended` | Attendance is recorded. |
| Booking Marked as No-Show | `booking.no_show` | A booking is resolved as a no-show. |
| Booking Cancelled | `booking.cancelled` | A booking is cancelled. |
The official app accepts the event at its unique Zapier REST Hook URL and then
exposes a mapping-friendly record:
| Zapier field | Meaning |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| `id` | Unique event/delivery ID; automatic delivery retries retain it. |
| `event_type` | Dotted Perkstar event name. |
| `event_created_at` | Source event time as an ISO 8601 timestamp. |
| `organization_id` | Connected Perkstar business ID. |
| Event-specific fields | The raw `data` fields flattened onto the record, such as `customerId`, `cardId`, or `occurredAt`. |
For booking events, the raw `data.id` is exposed as `resource_id` so it cannot
replace the trigger's primary `id`. See the [webhook event catalogue](/reference/webhook-events)
for required, optional, and nullable event fields. The app keeps documented
optional mapping fields present with `null` when the live event omits them, but
does not enrich every trigger with a customer profile. Add **Find Customer**
only when the event carries a customer ID and the Zap needs current contact
fields.
### Trigger options
* **Card (Optional)** is available on every named trigger except **Customer
Anonymised**, **Customer Lifecycle Group Changed**, and **Automation Fired**.
Leaving it blank accepts the event from every card.
* **Include Test Events** appears on **New Loyalty Transaction** and **Reward
Redeemed**. It is off by default so test API activity cannot start live
downstream steps; enable it only in a dedicated test Zap.
## Actions
Non-idempotent write actions use deterministic idempotency keys; customer
updates are naturally repeatable PATCHes. Loyalty activity and Wallet pushes
require the source app's stable transaction or event ID; use a real record ID
rather than a timestamp or random value. Perkstar automatically namespaces each
loyalty source ID by Zapier action and activity type. Retrying the same action
and source ID remains safe, while reusing an order ID for a different loyalty
operation cannot replay the wrong transaction. References that would exceed the
API's 180-character limit use a deterministic SHA-256 form.
Every POST-based Zapier action checks the current OAuth credential before it
looks for an earlier response. Refreshing the access token for the same
Perkstar connection preserves retry protection, while a revoked connection is
denied instead of replaying an earlier success.
The four focused loyalty actions provide guided fields for common merchant
jobs. **Record Loyalty Activity** remains available for workflows that need to
choose the activity type dynamically.
Each source transaction ID is permanently bound to its first canonical
customer, card, operation, and amount. An exact Zapier retry returns the
original result; reusing that ID with different inputs stops with a conflict
instead of silently returning or changing the first transaction.
All four focused loyalty actions and **Record Loyalty Activity** include
**Create Customer If Missing**, which defaults **off**. Leave it off when the
workflow should reward only existing members. Turn it on deliberately when a
lookup miss should create the customer and enrol them in the selected card
before applying the loyalty write. A missing or cross-business Customer ID is
never treated as permission to create a replacement customer.
| Zapier action | What it does | Important boundary |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create Customer | Creates a customer, or returns the existing customer when a matching `external_ref` is supplied. | Without `external_ref`, a duplicate email can return a conflict instead of overwriting a profile. |
| Update Customer | Updates the mapped fields on one existing Perkstar customer. | Blank or omitted mappings must be reviewed carefully; this action does not anonymise or delete a customer. |
| Enrol Customer in a Card | Finds a customer by Customer ID, email, phone, external reference, or pass barcode; can create a missing customer; and enrols them in the required active card. Returns available Apple/Google Wallet links. | An existing active pair is returned. An inactive or revoked pair halts for review rather than being silently reactivated; Wallet links can initially be `null`. |
| Add Stamp or Visit | Adds a positive whole number of stamps or visits to an active Stamp or Multipass card. | Its selector shows only Stamp and Multipass cards, and a mapped incompatible Card ID is rejected. A stable Source Activity ID supplies permanent duplicate protection. |
| Award Points | Adds a positive points amount, including up to two decimal places where the card permits it. | Its selector shows only active Points cards. The amount cannot exceed 100,000; a stable Source Points Award ID supplies permanent duplicate protection. |
| Record Purchase | Records an integer minor-unit purchase amount on an active Cashback or Discount card. | Its selector shows only Cashback and Discount cards. The purchase amount must be positive; a stable Source Order or Payment ID supplies permanent duplicate protection. |
| Redeem Loyalty Balance | Deducts a positive whole-number balance or prepaid visit from an active Stamp, Points, Cashback, or Multipass card without allowing the balance below zero. | Its selector excludes Coupon, Membership, Discount, Gift, and Ticket cards, which have separate or no balance-redemption flow. A mapped incompatible Card ID is rejected. |
| Record Loyalty Activity | Finds or creates the customer and enrolment when allowed, then records one compatible Stamp, Redeem, Check-in, Discount, or Points activity through `/marketplace/accrue`. | The Card and Source Transaction ID are required. Card-type mismatches fail, and the source ID supplies permanent duplicate protection. |
| Reverse Loyalty Transaction | Creates one compensating transaction for an eligible transaction previously recorded through Perkstar's marketplace API, found by Perkstar transaction ID, original source ID plus action, or exact external transaction ID. | A transaction can be reversed once. The action does not edit or delete the original ledger row. |
| Send Wallet Push | Sends a plain-text message of up to 180 characters to one enrolment's eligible Wallet passes. | Enrolment ID and Source Event ID are required. Push-marketing consent and a three-minute per-card cooldown are enforced; success cannot guarantee device display. |
### Action inputs
| Action | Required | Optional |
| --------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Create Customer | At least one of Email Address, Phone Number, or External Reference | First/last name, date of birth, marketing/ad-tracking consent, Unique Request ID |
| Update Customer | Customer ID and at least one profile or consent field to update | Profile and consent fields that are not changing may be omitted |
| Enrol Customer in a Card | Find Customer By, Customer Lookup Value, Card | Create Customer If Missing (defaults on), first/last name for a new customer, Enrolment Source |
| Add Stamp or Visit | Find Customer By, Customer Lookup Value, Card, Stamps or Visits to Add, Source Activity ID | Note, Create Customer If Missing (defaults off), first/last name |
| Award Points | Find Customer By, Customer Lookup Value, Card, Points to Award, Source Points Award ID | Note, Create Customer If Missing (defaults off), first/last name |
| Record Purchase | Find Customer By, Customer Lookup Value, Card, Purchase Amount (Minor Units), Source Order or Payment ID | Note, Create Customer If Missing (defaults off), first/last name |
| Redeem Loyalty Balance | Find Customer By, Customer Lookup Value, Card, Balance to Redeem, Source Redemption ID | Note, Create Customer If Missing (defaults off), first/last name |
| Record Loyalty Activity | Find Customer By, Customer Lookup Value, Card, Activity Type, Source Transaction ID | Purchase Amount (Minor Units), Balance Change, note, Create Customer If Missing (defaults off), first/last name |
| Reverse Loyalty Transaction | Find Transaction By and Transaction Reference | Original Perkstar Action when using the original source ID; Reason |
| Send Wallet Push | Enrolment or Pass, Message, Source Event ID | None |
The loyalty action accepts the wire-level activity types supported by the
public endpoint: `STAMP`, `REDEEM`, `CHECK_IN`, `DISCOUNT`, and `POINTS`.
`DISCOUNT` requires a positive amount in integer minor units. `POINTS` requires
either a balance change (up to two decimal places) or a positive purchase
amount. The selected card's type determines which values are valid.
**Send Wallet Push** supports `{firstName}`, `{lastName}`, `{balance}`,
`{cardName}`, `{installLink}`, `{shareLink}`, and `{orgName}` merge fields. Map
the originating trigger's stable `id` into **Source Event ID** so a retry of the
same source event is collapsed within Perkstar's 24-hour idempotency window.
## Searches
| Zapier search | Matching behavior | Result |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Find Customer | Looks up by exact Customer ID, email, phone, external reference, or pass barcode/serial. | Matching current customer records, or a not-found result the Zap can branch on. |
| Find Enrolment or Pass | Resolves Customer ID, email, phone, external reference, or pass barcode without creating records, then matches Card ID; status defaults to Active. | The same root result shape as Enrol Customer: nested customer and enrolment data plus available Wallet pass URLs. |
### Search-or-Create relationships
Zapier exposes both relationships explicitly, so a workflow can branch on a
search miss without constructing a custom API step:
| Zapier option | Search | Create action | Result on no match |
| -------------------------------- | ---------------------- | ------------------------ | ------------------------------------------------------------- |
| Find or Create Customer | Find Customer | Create Customer | Creates the customer from the mapped identity/profile fields. |
| Find or Enrol Customer in a Card | Find Enrolment or Pass | Enrol Customer in a Card | Enrols the selected customer in the selected active card. |
The enrolment pair still requires a customer and card. Repeatedly selecting the
same customer/card pair returns the existing active enrolment rather than
creating a duplicate. Perkstar never undoes an inactive or revoked status
implicitly: if the Active search misses but the create step finds that status,
the action halts with instructions to review the enrolment.
The app uses hidden dynamic-field helpers that paginate through up to ten pages
of 200 cards (2,000 total) before filtering. General selectors show every active
card; Add Stamp or Visit shows only Stamp and Multipass cards, Award Points only
Points cards, Record Purchase only Cashback and Discount cards, and Redeem
Loyalty Balance only Stamp, Points, Cashback, and Multipass cards. These helpers
are not advertised as standalone actions. A mapped Card ID is still checked
when the focused action runs, so mapping an incompatible card does not bypass
the selector.
Searches return current API state, while a trigger contains the event snapshot
produced at the time of the business change. If a Zap must preserve the exact
event context, store the trigger values before running later searches.
## Behavior the app does not expose
* No action edits card configuration, rewards, tiers, coupons, or orders.
* No action bypasses Perkstar consent, plan, card-type, tenant, or rate-limit
checks.
* `webhook.test` is not a customer-facing Zapier trigger.
* A trigger does not promise customer email, name, or phone unless that field is
part of the documented event payload.
* Searches do not scan another Perkstar business connected to the same Zapier
account.
## Related topics
- [Triggers, actions, and searches](/integrations/make/modules.md)
- [Zapier troubleshooting](/integrations/zapier/troubleshooting.md)
- [Make troubleshooting](/integrations/make/troubleshooting.md)
- [Integration gallery](/integrations/index.md)
- [Zapier](/integrations/zapier/index.md)