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


## Related topics

- [Send a wallet push](/api-reference/pushes/send-a-wallet-push.md)
- [Test mode](/fundamentals/test-mode.md)
- [Authentication and scopes](/fundamentals/authentication.md)
- [Perkstar developer platform](/index.md)
- [Build a POS integration](/guides/pos.md)