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

# Send push notifications

> Send a customer-safe wallet push or simulate delivery in test mode.

`POST /pushes` sends a push notification to the wallet pass attached to a
specific enrolment. The customer must have push marketing consent and an active
eligible card.

```bash theme={null}
curl --request POST "$PERKSTAR_API_URL/pushes" \
  --header "Authorization: Bearer $PERKSTAR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: summer-reminder-enrolment_123" \
  --data '{
    "enrollment_id": "enrolment_123",
    "message": "Hi {firstName}, your {cardName} is ready for your next visit."
  }'
```

## Merge fields

The message can use:

* `{firstName}`
* `{balance}`
* `{installLink}`
* `{shareLink}`
* `{cardName}`
* `{orgName}`

Keep the message useful without relying on a field that may be blank. Preview
the final wording in the dashboard before automating it.

## Delivery behaviour

* A three-minute cooldown applies per card across dashboard and API sends.
* `429` includes `Retry-After` when the cooldown or key limit is hit.
* The response reports attempted and failed platforms.
* Test credentials return `test_mode: true` without delivering or writing a broadcast row.
* A successful API response means Perkstar handed the update to the wallet platform; device display is controlled by Apple or Google.

<Note>
  Balance changes and reward events have their own service notifications and
  wallet refresh pipeline. Use this endpoint for business-authored messages, not
  as a replacement for posting the underlying loyalty transaction.
</Note>

## Safe automation

* Send only when the workflow has a clear customer purpose.
* Respect consent and suppression state returned by Perkstar.
* Use one idempotency key per intended message.
* Do not include health data, payment details, passwords, or other sensitive information.
* Rate-limit upstream triggers so a bulk sync cannot notify the same customer repeatedly.

The public Perkstar app for Zapier exposes this operation as **Send Wallet
Push**. See the [Zapier catalogue](/integrations/zapier/triggers-actions) for its
mapping and [Zapier data and security](/integrations/zapier/data-security)
before sending a marketing message through a Zap.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.