> ## 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 complete Perkstar module catalogue for Make, with inputs and safety boundaries.
The published review candidate contains 15 visible modules: one instant trigger with 29
event choices, 11 guided actions, two searches, and one universal API module.
Dynamic selectors load current active cards and other choices from the selected
Perkstar OAuth connection.
The app is available by invite link while Make reviews its Marketplace
listing. Event payloads can gain new optional fields; map only the fields a
scenario needs and handle absent or `null` values.
## Instant trigger
**Watch loyalty events** creates one attached Perkstar webhook for the event
selected in that module. Use separate trigger modules/scenarios for different
event subscriptions; do not subscribe to every event merely to discard most
bundles later. The trigger outputs a bundle only after an authenticated
Perkstar attestation binds its subscription, OAuth owner, signed delivery
headers, timestamp, and event envelope.
### Customer lifecycle
| Event choice | 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 event does not represent an operator-created saved segment.
Perkstar stores the first classification as a baseline without emitting an
event, preventing a newly connected scenario from replaying every customer.
### Wallet, scanner, expiry, and referrals
| Event choice | Perkstar event | Fires when |
| --------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
| Wallet pass installed | `wallet.installed` | Perkstar first observes an Apple or Google Wallet install; Google observation is periodic. |
| Card scanned | `card.scanned` | An online Perkstar Scanner lookup successfully resolves a 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 the same loyalty-card programme. |
`referral.created` is customer-to-customer loyalty activity. It is not a
merchant, agency, partner, or affiliate-referral event.
### Loyalty activity
| Event choice | 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
| Event choice | 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
| Event choice | 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
| Event choice | 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
| Event choice | 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 diagnostic `webhook.test` event is deliberately excluded. See the
[webhook event catalogue](/reference/webhook-events) for every required,
optional, and nullable event field.
### Trigger inputs and output
| Input | Behaviour |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event | Required. Creates a subscription for exactly one of the 29 event types above. |
| Card | Optional. Use it only when the selected event carries a Card ID; otherwise leave it blank. A blank Card accepts the selected event across all cards. |
| Include test events | Available on the trigger and off by default. It affects only event types that can carry test activity; enable it only in an isolated test scenario. |
Each bundle preserves the common event envelope: stable **Event ID**, dotted
**Event type**, source **Created**, **Organisation ID**, and a nested **Event
data** collection containing the selected event's fields. **Created** is an
integer containing Unix seconds. The nested `data.occurredAt` field is the same
business occurrence time in ISO 8601 text form. Neither value is the time Make
received or executed the scenario. For booking events, `data.id` stays inside
**Event data** and does not replace the outer Event ID. Trigger bundles are
snapshots; use a search only when a later step genuinely needs current customer
or enrolment state.
The module publishes a static synthetic sample so mapping fields are available
without reading a real customer's latest event. Live webhook deliveries use
the same envelope and still complete Perkstar's server-attested verification
before Make emits a bundle.
## Guided actions
The guided modules validate common merchant workflows and are preferred over
the universal API module. A focused loyalty action filters its Card selector to
compatible active programmes and validates a mapped Card ID again at runtime.
| Guided action | What it does | Important boundary |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create a customer | Creates a customer using the supplied identity fields. | Requires a stable **Unique request ID** and at least one of email, phone, or external reference. Keep the request ID unchanged only when retrying that same create. |
| Find or create a customer by external reference | Looks up one exact external reference and creates the customer only when no match exists. | External reference is required and must remain stable in the source system. It does not fuzzy-match email, phone, or name. |
| Update a customer | Updates explicitly mapped profile or consent fields on one existing customer. | Requires Customer ID. Map at least one field. It cannot change external reference; omitted fields are not an instruction to blank them. |
| Find or enrol a customer in a card | Resolves the customer and returns an existing active customer/card enrolment, or enrols the customer in the selected card. | A revoked or inactive pair is not silently reactivated. Creating a missing customer must be explicitly enabled and pass identity validation. |
| Add a stamp or visit | Adds a positive whole number of stamps or visits to an active Stamp or Multipass card. | Requires a stable Source activity ID. Incompatible or inactive cards are rejected. |
| Award points | Adds a positive points value, including up to two decimals when the card supports it. | Its selector shows active Points cards. The award cannot exceed 100,000; a stable Source points award ID is required. |
| Record a purchase | Records a positive integer minor-unit purchase on an active Cashback or Discount card. | Do not pass a decimal currency amount. A stable Source order or payment ID is required. |
| Redeem loyalty balance | Deducts a positive whole-number balance or prepaid visit without allowing the balance below zero. | Supports active Stamp, Points, Cashback, and Multipass cards; it excludes Coupon, Membership, Discount, Gift, and Ticket flows. |
| Record loyalty activity (advanced) | Selects a compatible `STAMP`, `REDEEM`, `CHECK_IN`, `DISCOUNT`, or `POINTS` activity dynamically. | Card, activity type, and stable Source transaction ID are required. Prefer a focused module when the activity type is known. |
| Reverse a loyalty transaction | Writes one compensating transaction for an eligible marketplace transaction found by Perkstar transaction ID or its stable original reference. | A transaction can be reversed once. The module does not edit or delete the original ledger row and does not infer partial-refund policy. |
| Send a Wallet push | Sends a plain-text message of up to 180 characters to one enrolment's eligible Wallet passes. | Enrolment and stable Source event ID are required. Push-marketing consent and a three-minute per-card cooldown are enforced; API success cannot guarantee device display. |
### Loyalty identity and retries
For **Add a stamp or visit**, **Award points**, **Record a purchase**, **Redeem
loyalty balance**, and **Record loyalty activity (advanced)**, keep the source
module's order, payment, attendance, or redemption ID unchanged when Make
retries an incomplete execution. Perkstar gives each module/operation its own
deduplication namespace and permanently binds the canonical source reference to
the first customer, card, operation, and amount.
An exact retry returns the original result. Reusing that reference with
different inputs produces a conflict instead of changing the first
transaction. Do not replace a stable source ID with `now`, a random UUID, or a
new Make execution ID on retry.
The Wallet push supports `{firstName}`, `{lastName}`, `{balance}`, `{cardName}`,
`{installLink}`, `{shareLink}`, and `{orgName}` merge fields. Map the source
bundle's stable record or event ID into **Source event ID** so repeated handling
of one event is collapsed inside Perkstar's idempotency window.
## Searches
| Search | Matching behaviour | Result |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search customers | Optional exact email, phone, external reference, or pass barcode/serial filters, plus an optional Created after. | Current matching customers, up to the configured Limit. |
| Search enrolments or passes | Optional Customer ID and Card filters. Status defaults to Active even when the field is left blank or an empty value is mapped. | Active enrolments, balance/activity values, and available Apple/Google Wallet links, up to the Limit. Choose Inactive or Revoked when historical passes are needed. |
Searches do not create or change data. If a no-match should create a customer,
use **Find or create a customer by external reference** with a genuine stable
external reference. If it should create a card relationship, use **Find or
enrol a customer in a card**. Keep a Make router/filter for business outcomes
that should stop, notify an operator, or follow a different path on no match.
Both searches cursor-page and return no more bundles than **Limit**. Limit
defaults to 10 and accepts 1–3,200.
Dynamic Card selectors return up to 500 active cards. Their Limit defaults to
200 and accepts 1–500. General selectors show every active card within that
limit; focused action selectors show only compatible card types. A manually
mapped ID still goes through the same tenant, active, and type checks when the
module runs.
## Make an API call
**Make an API call** is the universal module required for a public Make app. Use
it only when the operation exists in Perkstar's [public API
reference](/api-reference) and no guided module fits.
* Enter a path relative to `https://dashboard.perkstar.co.uk/api/v1`, for
example `/customers/{customerId}`. Do not enter a different host or a full
callback URL.
* Select the supported HTTP method and supply only the documented query string
and JSON body. The module supplies OAuth authentication and deliberately does
not expose arbitrary request headers. Keeping authentication and transport
control headers app-owned prevents a scenario from replacing the OAuth
credential, host, content type, or other security-sensitive values.
* For a supported POST, map a stable value of at most 255 characters into the
optional dedicated **Idempotency key** field. The app sends it only as
`Idempotency-Key`; a random value per Make retry can duplicate a write.
* The exact scopes granted to the connection still apply. Guided connections
use eight baseline scopes; five additional advanced scopes are optional and
require explicit selection and renewed OAuth consent. The module cannot
access private dashboard routes, another Perkstar business, or an operation
outside that connection's granted scopes.
* Handle `4xx`, `429`, and `5xx` responses deliberately. Prefer a guided module
for loyalty writes because it also constructs and validates the permanent
source transaction identity.
A universal API module is not a security or product-boundary escape hatch. Do
not use it to recreate an unsupported card editor, bulk-marketing sender, or
undocumented dashboard workflow.
## Deliberately not exposed
* No module edits card configuration, rewards, tiers, coupons, or orders.
* No module bypasses Perkstar consent, plan, card-type, tenant, account-state, or
rate-limit checks.
* `webhook.test` is not a choice in **Watch loyalty events**.
* An event bundle does not promise customer email, name, or phone unless the
documented event carries it.
* Searches and dynamic selectors never read another business connected to the
same Make organisation.
## Related topics
- [Triggers, actions, and searches](/integrations/zapier/triggers-actions.md)
- [Zapier troubleshooting](/integrations/zapier/troubleshooting.md)
- [Make troubleshooting](/integrations/make/troubleshooting.md)
- [Integration gallery](/integrations/index.md)
- [Zapier](/integrations/zapier/index.md)