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

> Diagnose private-beta access, OAuth, instant triggers, modules, queues, retries, rate limits, and consent failures.

Start with the scenario's execution history, incomplete executions, and the
connected Perkstar business. Record the module name, UTC time, status/code, and
Perkstar `X-Request-Id` before retrying. Never copy an OAuth token, Make webhook
URL, or full customer bundle into a support message.

## Access and connection

<AccordionGroup>
  <Accordion title="Perkstar does not appear in Make">
    The app is a private beta and is not publicly searchable in Make's app
    catalogue. Confirm that Perkstar enabled the Make organisation you are
    currently using. An eligible Perkstar plan alone does not grant beta access.
  </Accordion>

  <Accordion title="The Perkstar business is not eligible">
    Make access requires Growth, Scale, Enterprise, or Franchise. Check the
    current plan and that OAuth is opening the intended business. Free and
    Starter businesses cannot connect the integration.
  </Accordion>

  <Accordion title="OAuth shows the wrong Perkstar business">
    Cancel instead of approving. Switch to the correct Perkstar organisation,
    then add a new connection. A later Make filter cannot change the tenant
    bound to an OAuth grant.
  </Accordion>

  <Accordion title="OAuth succeeded but the module still asks for a connection">
    Reopen the module and select the newly created connection explicitly. Make
    connections belong to a team context; confirm the scenario is in the team
    where the connection was created and that your Make role can use it.
  </Accordion>

  <Accordion title="The connection repeatedly fails or asks to reconnect">
    Reauthorise it once, then run a read-only **Search customers** test. If
    Perkstar access was revoked, a new consent is required; retrying the old
    execution cannot restore the grant. Retest every active scenario sharing
    that connection.
  </Accordion>
</AccordionGroup>

## Watch loyalty events

<AccordionGroup>
  <Accordion title="Run once receives no bundle">
    Start **Run once** before performing the event. Confirm the module selected
    the exact dotted business event, correct Perkstar connection, and correct
    Card when a Card filter is set. The generic `webhook.test` diagnostic is not
    one of the module's 29 event choices.
  </Accordion>

  <Accordion title="A live event did not run the scenario">
    Confirm the scenario is saved and On, its attached webhook still exists, the
    OAuth connection is authorised, and the business operation actually reached
    a completed state. Inspect Make's webhook queue, execution history, and
    incomplete executions. If no bundle exists, report the event ID and UTC time
    to Perkstar support without sharing the callback URL.
  </Accordion>

  <Accordion title="The scenario was Off and events appeared later">
    Turning a scenario Off does not necessarily delete its attached webhook.
    Make can retain webhook state or queued bundles depending on configuration.
    Inspect timestamps and the webhook queue before processing; delete the
    attached webhook if the upstream subscription should end.
  </Accordion>

  <Accordion title="The same event was processed twice">
    Perkstar delivery is at least once. Compare the stable event ID. Add a
    uniqueness check or Make Data Store guard before a non-idempotent
    destination write, and use the same ID as the downstream source reference.
  </Accordion>

  <Accordion title="Events arrived out of order">
    This is allowed. Compare Event Data `occurredAt` or the outer Created value
    and the current destination state. Do not order business changes by Make
    execution time.
  </Accordion>

  <Accordion title="A field is absent or null">
    Event bundles are not enriched with a full customer profile, and optional
    fields do not apply to every occurrence. Review the [event
    catalogue](/reference/webhook-events), guard mappings, and add **Search
    customers**, **Search enrolments or passes**, or a documented read through
    **Make an API call** only when current state is appropriate.
  </Accordion>

  <Accordion title="Wallet Pass Installed has not fired">
    Creating a pass or opening a save link is not installation evidence. Apple
    normally reports a device registration. Google is observed periodically;
    provider response, object age, and projector backlog can extend the delay. A
    business's first Google subscription uses a completed sweep as a no-event
    baseline, so enable and test before distributing install links.
  </Accordion>

  <Accordion title="An offline card scan did not fire">
    **Card Scanned** covers successful online Perkstar Scanner lookups only. A
    cache-only offline scan, dashboard search, or POS customer lookup does not
    cross the webhook boundary.
  </Accordion>

  <Accordion title="Customer Lifecycle Group Changed did not return everyone in a segment">
    The event reports movement among Perkstar's six lifecycle groups, not entry
    into a saved segment. Initial classification is stored as a no-event
    baseline to avoid replaying the customer base.
  </Accordion>
</AccordionGroup>

## Searches and actions

| Symptom                                       | Likely cause                                                                                         | What to do                                                                                               |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Search customers returns no bundle            | Exact email, phone, external reference, pass serial, or Created after filter does not match          | Correct or remove the filter and keep a narrow Limit. Use `GET /customers/{id}` for a known Customer ID. |
| Search enrolments or passes has no Wallet URL | Pass issuance is pending, filters do not match, or that Wallet platform is not configured            | Check Customer ID, Card, and Status; retry later and never construct an install URL.                     |
| Find or Enrol reports inactive/revoked        | That customer/card pair exists and Perkstar will not silently undo its status                        | Review and explicitly reactivate it in Perkstar; do not create a duplicate customer.                     |
| A Card is absent from a focused module        | The card is inactive or its type is incompatible                                                     | Choose the matching module/card type. Manually mapped incompatible IDs are rejected too.                 |
| `400 ambiguous_default_card`                  | Several active cards exist and none was selected                                                     | Select the intended Card explicitly.                                                                     |
| `401` or connection error                     | OAuth grant is invalid, expired beyond refresh, or revoked                                           | Reauthorise, run a read-only test, then retest every affected scenario.                                  |
| `403` permission error                        | Grant lacks the operation's scope, plan/role is ineligible, or the operation is forbidden            | Reauthorise the official connection and confirm plan/role. Never substitute a raw API key.               |
| `403 push_marketing_consent_required`         | Customer lacks Wallet push-marketing consent                                                         | Stop the message and follow the approved consent process; do not route around it.                        |
| `404`                                         | Customer, enrolment, card, or transaction is not in this business or no longer exists                | Check the connection and opaque IDs; do not reuse an ID from another tenant.                             |
| `409` creating a customer                     | A conflicting customer exists and no stable external-reference upsert was used                       | Find the existing customer or use the source system's genuine stable external reference.                 |
| `409 external_transaction_id_conflict`        | A source ID was reused with different customer, card, operation, or amount                           | Keep original inputs for a retry, or use the different source record's own ID.                           |
| `409 webhook_subscription_limit_reached`      | This Make app, installing Perkstar user, and business share 200 subscriptions, including paused rows | Remove unused Make webhooks, confirm detach, then create the new webhook again.                          |
| `422` loyalty validation                      | Activity/amount does not match the Card type, or a source reference belongs to the other environment | Correct the mapping. Do not hide the error by generating a new source ID.                                |
| `429`                                         | API limit or three-minute Wallet-push card cooldown                                                  | Honour `Retry-After`; reduce iterators, concurrency, and bursts.                                         |
| `5xx` or network timeout                      | Temporary Perkstar or network failure                                                                | Retry the same logical operation with unchanged stable IDs; check [API status](/support/status).         |

## Make an API call

| Symptom                                                 | What to check                                                                                                                            |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid or unsupported URL                              | Use a relative public v1 path such as `/customers/{id}`. Do not pass a full host or private dashboard path.                              |
| Missing authentication                                  | Select the Perkstar connection. The module supplies OAuth and has no arbitrary-header input.                                             |
| Duplicate POST after retry                              | Map the same stable value (up to 255 characters) into **Idempotency Key** on every attempt and inspect whether the first call succeeded. |
| Guided module succeeds but universal call returns `403` | The connection did not grant the required optional permission, or the operation is not available to that business or scope.              |
| Response body does not match a mapping                  | Confirm the current public API schema and guard optional fields; do not assume a dashboard response shape.                               |

## Incomplete executions and safe replay

Before resolving or replaying an incomplete Make execution:

1. Decide whether the earlier Perkstar or destination module may already have
   succeeded.
2. Preserve the original source event, order, payment, activity, or request ID,
   and keep every mapped field that contributes to the request fingerprint
   unchanged—including customer identity, Card, activity type, amount, note,
   metadata, and any create-if-missing fields.
3. Fix non-retryable validation, permission, consent, or conflict errors first.
4. Retry the failed path once and inspect the returned Perkstar record.
5. Confirm no iterator/router path can execute the same write again with a new
   source ID.

To reverse a loyalty write, prefer its returned Perkstar Transaction ID. If only
the upstream source ID is available, use the exact original reference and
operation expected by **Reverse a loyalty transaction**.

## Webhook attestation failure

The official trigger sends the received event and signed headers back to
Perkstar over OAuth before it outputs a normal bundle. If that check fails, do
not map around it: confirm the attached webhook still belongs to the selected
connection, the event was not altered, the execution is recent, and the
Perkstar business and OAuth grant remain active. Keep the callback URL secret.

A temporary verifier outage can leave a Make execution failed or incomplete
after its callback was already acknowledged. Resume the same execution after
service recovers and preserve the original Event ID. Exact proofs remain
recoverable for up to 90 days; older proofs fail closed. See [Webhooks and
instant scenarios](/integrations/make/webhooks).

## Ask for help

Email [support@perkstar.co.uk](mailto:support@perkstar.co.uk) with:

* the Perkstar business name;
* the Make organisation/team and scenario name (not a private link);
* the Perkstar module and approximate UTC time;
* the Make execution ID and Perkstar `X-Request-Id`, event ID, or delivery ID
  when available; and
* the status/error code with secrets and personal fields removed.

For suspected credential exposure or a personal-data incident, contact
[privacy@perkstar.co.uk](mailto:privacy@perkstar.co.uk) immediately.


## Related topics

- [Make data and security](/integrations/make/data-security.md)
- [Make scenario recipes](/integrations/make/recipes.md)
- [Refunds and troubleshooting](/integrations/loyverse/refunds-troubleshooting.md)
- [Make](/integrations/make/index.md)
- [Square refunds and troubleshooting](/integrations/square/refunds-troubleshooting.md)