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

# Make scenario recipes

> Reliable Perkstar scenario patterns for onboarding, loyalty activity, operations, and consented Wallet messaging.

These are private-beta patterns, not public one-click Make templates. Build them
with the named modules, test with controlled records, and define an error route
before processing production customers.

## Send a new member to a CRM or sheet

**Trigger:** Watch loyalty events → New customer enrolment

**Then:** Make an API Call (`GET /customers/{customerId}`) → create or update
the destination record

1. Select a Card in the trigger if the destination represents one programme.
2. When **Event Data** includes Customer ID, use it in the relative API path;
   do not make a second identity guess from name, email, or phone. Route an
   event with no Customer ID to review or a workflow that can resolve its
   documented enrolment context.
3. Make the read only when the destination genuinely needs current profile
   fields. **Search customers** does not accept Customer ID; it is for optional
   exact email, phone, external-reference, pass-serial, and Created after
   filters.
4. Use the Perkstar customer or enrolment ID as the destination's stable external
   key.
5. Add a route for a `404` or missing Customer ID rather than creating an
   unidentified destination record.

<Note>
  Joining a loyalty card is not blanket consent for email, SMS, advertising, or
  another app's marketing list. Map purpose-specific consent only when the
  business has evidence for that destination and channel.
</Note>

## Create an external lead once, then enrol them

**Trigger:** A qualified lead, booking, or checkout in another Make app

**Actions:** Find or Create a Customer by External Reference → Find or Enrol a
Customer in a Card

1. Map the source app's immutable customer/contact ID into **External
   Reference**. Namespace it when multiple stores can produce the same value,
   for example `hubspot:portal-42:contact:1042`.
2. Map only the identity/profile fields authorised for Perkstar.
3. Select the intended active Card explicitly.
4. Map the returned customer into **Find or Enrol a Customer in a Card**.
5. Store returned Customer ID and Enrolment ID in the source system where
   possible.
6. If Wallet links are initially unavailable, use **Search enrolments or
   Passes** later with Customer ID, Card, and Active status instead of
   constructing a link.

This pattern makes a repeated source event return the same customer and active
customer/card relationship. It never silently reactivates an inactive or
revoked enrolment.

## Record a paid order exactly once

**Trigger:** A paid or completed order in a commerce/POS module

**Action:** Add a stamp or visit, Award points, or Record a purchase

Choose the focused action that matches the Perkstar card:

| Card intent             | Guided module        | Amount                                                  |
| ----------------------- | -------------------- | ------------------------------------------------------- |
| Stamp or visit credit   | Add a stamp or visit | Positive whole-number count                             |
| Direct points award     | Award points         | Positive points value                                   |
| Cashback/discount spend | Record a purchase    | Positive integer minor units, such as `1250` for £12.50 |

Map the upstream order/payment ID into the action's Source ID. Prefix it when
several stores can emit the same numeric ID:

```text theme={null}
shopify:store-12:order:94721
```

Use a Make error handler that keeps that value and every fingerprinted input
unchanged on retry—including customer identity, Card, activity type, amount,
note, metadata, and create-if-missing fields. If the scenario needs to choose
an activity type dynamically, use **Record loyalty activity (advanced)** and
validate Card, type, delta, and purchase amount on every route.

<Warning>
  Never generate a new source transaction ID when an incomplete execution is
  retried. A stable upstream ID is what prevents a delayed or duplicate order
  bundle from crediting loyalty twice.
</Warning>

## Reverse a refunded order

**Trigger:** A completed refund in the source app

**Action:** Reverse a Loyalty Transaction

Prefer the Perkstar transaction ID returned and stored by the original earn
scenario. If only the original source order/payment ID is available, use the
same value and the exact original Perkstar operation when the module asks for
it. Perkstar writes a compensating ledger row and returns the existing reversal
when the same original transaction was already reversed.

Partial-refund rules vary. Decide whether a partial refund should leave the
original loyalty transaction, reverse it fully, or be handled by a separate
approved adjustment before activating the scenario. The reversal module does
not infer this policy from arbitrary refund data.

## Route an operational loyalty event

**Trigger:** Watch loyalty events → Reward redeemed, Loyalty tier changed,
Feedback Submitted, Booking Marked as No-Show, or another selected event

**Then:** Filter → approved operations channel or case-management app

Include the Perkstar event ID, source time, and only the opaque customer,
enrolment, booking, or card ID an authorised operator needs. Avoid copying full
contact details or free-text feedback into a broad channel. Use separate
trigger modules/scenarios for materially different access and retention rules.

## Send a consented Wallet reminder

**Trigger:** A deliberate business rule in another app

**Actions:** Search enrolments or passes → Send a Wallet push

* Target one current enrolment.
* Map the upstream bundle's stable event/record ID into **Source Event ID** and
  preserve it across retries.
* Keep the expanded message at or below 180 characters.
* Expect `403 push_marketing_consent_required` when consent is absent; route it
  to a safe stop, not a workaround.
* Respect `Retry-After` and the shared three-minute per-card cooldown on `429`.
* Do not iterate a large customer list into rapid sends without an approved
  frequency cap and queue.

## Use Make an API Call without duplicating a write

Use **Make an API Call** only for a documented public v1 operation without a
guided module.

1. Confirm the operation and schema in the [API reference](/api-reference).
2. Use the relative path, never another host.
3. For supported POST requests, map a stable upstream value of at most 255
   characters into the optional dedicated **Idempotency Key** field, and keep
   it unchanged for every retry of that logical request.
4. Add an error route for `429` and transient `5xx` results.
5. Treat `400`, `403`, `404`, `409`, and `422` as state or validation problems,
   not blind-retry candidates.
6. Inspect the Perkstar record after a timeout before changing any identifier.

Prefer a guided module whenever it exists. The universal module cannot add
product-specific card filters or construct the permanent source transaction
identity as safely as the focused loyalty actions.

## Production checklist

* [ ] The Make organisation, team, scenario owner, Perkstar business, and every
  destination owner are recorded.
* [ ] Each connection name identifies the tenant and environment.
* [ ] Each instant trigger selects one event and an explicit Card where useful.
* [ ] Every loyalty write uses a stable source ID and survives a duplicate test.
* [ ] Routers handle empty search results and optional event fields.
* [ ] Error handlers preserve original IDs and expose terminal failures to an
  operator.
* [ ] Consent and suppression are tested with both allowed and blocked records.
* [ ] `429`, non-retryable `4xx`, incomplete executions, and destination
  failures are monitored.
* [ ] Scenario history, webhook queues, Data Stores, and destinations have
  intentional retention and access.
* [ ] Disconnect, rights-request, incident, and downstream deletion procedures
  have named owners.

For failures, use [Make troubleshooting](/integrations/make/troubleshooting).


## Related topics

- [Make](/integrations/make/index.md)
- [Webhooks and instant scenarios](/integrations/make/webhooks.md)
- [Make troubleshooting](/integrations/make/troubleshooting.md)
- [Connect Perkstar to Make](/integrations/make/setup.md)
- [Make data and security](/integrations/make/data-security.md)