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

# Zapier troubleshooting

> Diagnose public-app access, OAuth, instant triggers, actions, searches, rate limits, and consent failures.

Start with Zap history and the connected Perkstar business. Record the
step name, event or request time, status, and any Perkstar `X-Request-Id` before
retrying. Never copy an OAuth token, unique hook target URL, or full customer
payload into a support message.

## Connection and access

<AccordionGroup>
  <Accordion title="Perkstar does not appear in Zapier">
    Open the [official public Beta
    listing](https://zapier.com/apps/perkstar/integrations), confirm you are
    signed in to the intended Zapier account, and search for **Perkstar** rather
    than a similarly named app. You can also use **App connections → Add
    connection**. No invitation is required. If a managed Zapier workspace
    restricts apps, ask its administrator to allow Perkstar.
  </Accordion>

  <Accordion title="Zapier opens Perkstar signup instead of the intended business">
    The public listing does not create or join a Perkstar business. If you are
    an existing team member, accept the Perkstar team invitation sent to your
    exact email address and sign in with that account before reconnecting. Do
    not create a second business just to authorise Zapier. If you are a new
    customer, finish Perkstar account and plan setup first.
  </Accordion>

  <Accordion title="The business is not eligible">
    Zapier is available to Growth, Scale, Enterprise, and Franchise businesses.
    Confirm the current Perkstar plan and that you are connecting the intended
    business. Free and Starter businesses must upgrade before connecting.
  </Accordion>

  <Accordion title="OAuth opens the wrong Perkstar business">
    Cancel instead of approving. Sign out or switch to the correct Perkstar
    organisation, then start the connection again. One connected account is
    tenant-scoped to one business.
  </Accordion>

  <Accordion title="I need more than one Perkstar connection">
    One connected account is scoped to one Perkstar business, but it can be
    reused across many Zaps. Add a separate Perkstar connection for each other
    business and give each connection a clear name. A Zapier account can hold
    multiple Perkstar connections.
  </Accordion>

  <Accordion title="The connection test fails or repeatedly asks to reconnect">
    Reauthorise the Perkstar connected account in Zapier, then test every
    enabled Zap that uses it. If access was revoked in Perkstar, a new approval
    is required; retrying the old task does not restore the grant.
  </Accordion>
</AccordionGroup>

## Instant triggers

<AccordionGroup>
  <Accordion title="The test trigger finds no event">
    Confirm the Zap uses the correct Perkstar business and named event. Start
    the Zapier test/listen step first, then perform that exact event. If a card
    filter is present, confirm the event belongs to the selected active card.
    The diagnostic `webhook.test` event does not satisfy a business-event
    trigger.
  </Accordion>

  <Accordion title="A live event does not start the Zap">
    Check that the Zap is published and enabled, the connected account is still
    authorised, and the expected Perkstar business event actually completed.
    Inspect Zap history. Perkstar keeps app-managed delivery attempts out of the
    custom-webhook dashboard so their callback URL and signing secret cannot be
    changed behind Zapier's back; quote the event time and ID to Perkstar
    support if Zap history is not enough.
  </Accordion>

  <Accordion title="The Zap ran twice">
    Automatic retries keep one logical delivery ID and should deduplicate.
    Confirm the runs have the same trigger `id`. Protect destination writes with
    the Perkstar ID or another stable source reference.
  </Accordion>

  <Accordion title="Events arrived out of order">
    This is allowed. Compare the event-specific `occurredAt` timestamp and the
    destination's current state. The exposed `event_created_at` field expresses
    that same source-event time in ISO 8601; the internal signing timestamp is
    the delivery-attempt time.
  </Accordion>

  <Accordion title="A field is missing from the trigger">
    Documented optional mapping fields can be `null` when they do not apply, and
    trigger bodies are not automatically enriched with a customer profile.
    Review the [event catalogue](/reference/webhook-events), guard optional
    mappings, and add **Find Customer** or **Find Enrolment or Pass** only when
    current state is appropriate.
  </Accordion>

  <Accordion title="Wallet Pass Installed has not fired yet">
    Creating a pass or opening its save link is not installation evidence. Apple
    normally reports installation through its device callback. Google is
    observed periodically; recently issued passes are eligible on the 15-minute
    projector, while object age, provider cadence, and projector backlog can
    extend the delay. Check the Zap and pass again after a later completed sweep
    rather than treating 15 minutes as an SLA. The trigger fires only for the
    first observed install of that pass. A business's first Google-install
    trigger uses its first check as a no-event baseline; tracking begins after
    that warm-up, so enable and test the Zap before distributing install links.
  </Accordion>

  <Accordion title="An offline card scan did not start the Zap">
    **Card Scanned** covers successful online Perkstar Scanner lookups only. A
    lookup served solely from the scanner's offline cache never reaches the
    webhook boundary and does not fire this trigger. Dashboard searches and POS
    customer lookups are also excluded.
  </Accordion>

  <Accordion title="Customer Lifecycle Group Changed did not return every segment member">
    The trigger reports movement between Perkstar's six exclusive lifecycle
    groups, not entry into or exit from an operator-created saved segment. A
    customer's first classification is stored as a baseline without an event,
    preventing a new Zap from replaying the entire customer base. For the first
    interested trigger in a business, allow one completed periodic sweep to
    establish that baseline before expecting later transitions.
  </Accordion>

  <Accordion title="Customer Card Expired fired again after an extension">
    The event belongs to one enrolment and one effective expiry instant. If the
    enrolment is extended or reissued and later reaches a different expiry,
    another event is expected. Use `enrollmentId` plus `expiresAt` as the
    business identity when the destination needs its own duplicate protection.
  </Accordion>

  <Accordion title="New Customer Referral is not a merchant referral">
    This trigger is customer-to-customer loyalty activity. It includes both the
    referrer's and referred customer's IDs, but it does not represent an agency,
    merchant, partner, or affiliate invitation.
  </Accordion>
</AccordionGroup>

## Searches and actions

| Symptom                                       | Likely cause                                                                                                     | What to do                                                                                                                 |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Find Customer returns no match                | Wrong lookup type/value, cross-business Customer ID, email casing/format issue, or exact phone format differs    | Prefer the trigger's Customer ID or a stable external reference/pass barcode; use the same phone format the source stores. |
| Find Enrolment or Pass returns no Wallet URL  | Pass issuance is still pending or that Wallet platform is not configured                                         | Retry the search later; never construct an install URL.                                                                    |
| Find or Enrol reports a revoked/inactive pass | The customer/card pair already exists and Perkstar will not silently undo its status                             | Review and explicitly reactivate the enrolment in Perkstar before retrying; do not create a duplicate customer.            |
| A card is absent from a focused action        | The card type is not valid for that action or the card is not active                                             | Choose the matching action/card type; mapping an incompatible Card ID is rejected too.                                     |
| `400 ambiguous_default_card`                  | The business has several active cards and no card was selected                                                   | Select the intended card explicitly in the Zap step.                                                                       |
| `401` or connection error                     | OAuth grant is invalid, expired beyond recovery, or revoked                                                      | Reconnect the Perkstar account, then retest affected Zaps.                                                                 |
| `403` permission error                        | The OAuth grant lacks the required access or the operation is not allowed for the business                       | Reauthorise the official connection and confirm plan/role eligibility; do not substitute a raw API key.                    |
| `403 push_marketing_consent_required`         | The customer has not consented to marketing Wallet pushes                                                        | Stop the message. Obtain and record valid consent through an approved process before another marketing send.               |
| `404`                                         | Customer, enrolment, card, or original transaction does not belong to the connected business or no longer exists | Check the connection and mapped opaque IDs; do not reuse an ID from another business.                                      |
| `409` creating a customer                     | A conflicting customer exists and the Zap did not use a stable `external_ref` upsert                             | Find the existing customer or provide the source system's stable external reference.                                       |
| `409 external_transaction_id_conflict`        | A loyalty Source ID was reused with a different customer, card, operation, or amount                             | Keep the original inputs for a retry, or use the genuinely different source record's own stable ID.                        |
| `409 webhook_subscription_limit_reached`      | This OAuth connection owns 200 instant-trigger subscriptions, including paused rows from an interrupted cleanup  | Turn off/remove unused instant triggers, confirm unsubscribe succeeds, then enable the new trigger again.                  |
| `422` recording loyalty                       | Activity does not match the selected card type or the source reference belongs to the other environment          | Correct the card/activity mapping; never hide the error by generating a new transaction reference.                         |
| `429`                                         | Credential rate limit or three-minute Wallet-push card cooldown                                                  | Let Zapier wait for `Retry-After`; reduce loops and burst frequency.                                                       |
| `5xx` or network timeout                      | Temporary Perkstar or network failure                                                                            | Retry the same logical task with the same stable identifiers; check [API status](/support/status).                         |

## Safe replay

Before retrying or manually replaying a failed task:

1. Decide whether the earlier action may already have succeeded.
2. Keep the same source ID field value. Perkstar recreates the same
   action-specific external transaction ID, including its deterministic hash
   form when needed.
3. Fix a non-retryable validation, permission, or consent error first.
4. Retry from Zapier once and inspect the returned Perkstar record.
5. Replay once, then inspect the result before trying again.

To reverse a Zapier loyalty write, prefer its returned **Perkstar Transaction
ID**. If only the original source ID is available, select **Original Source
Transaction ID** and the exact Perkstar action that recorded it. If mapping the
returned **External Transaction ID**, map it exactly without removing the
`zapier:` namespace.

## Ask for help

For a problem in a Zap workflow, use [Zapier
Support](https://zapier.com/app/get-help) first. That route preserves the Zap
and run context for Zapier's first-line troubleshooting; Zapier will escalate
an actionable Perkstar integration report to us when needed. Contact [Perkstar
Support](mailto:support@perkstar.co.uk) directly for a Perkstar account, plan,
team invitation, business-selection, or OAuth-consent problem.

For a support request, keep the failed run in Zap history and
include:

* the Perkstar business name;
* the Zapier trigger, action, or search name;
* the approximate UTC time and Zap run/task ID;
* the Perkstar `X-Request-Id`, event ID, or delivery ID when available; and
* the status/code with secrets and personal fields removed.

Do not delete the failed history before support has finished tracing it. Never
send a password, OAuth token, refresh token, webhook target URL, or full
customer payload.

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


## Related topics

- [Zapier data and security](/integrations/zapier/data-security.md)
- [Zapier](/integrations/zapier/index.md)
- [Zapier recipes](/integrations/zapier/recipes.md)
- [Connect Perkstar to Zapier](/integrations/zapier/setup.md)
- [Changelog](/changelog.md)