> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Delivery Notifications

> Email, SMS and webhook notifications sent to shoppers and systems when a shipment reaches a trigger, with templates, filters and delivery metrics.

**Available to all Post-Purchase customers.** Users with the Campaign Manager role have view-only access to Notifications.

## Summary

Delivery Notifications send an email, an SMS or a webhook when a shipment reaches a trigger, from order confirmation to delivery, failed attempts, delays and collection reminders. You choose the trigger, the channel, the template and which shipments qualify, and the portal reports how each notification performs.

## Who it’s for

Customer service and e-commerce teams that want shoppers told about their delivery before they ask, and integration teams that need their own systems updated on every shipment event through webhooks.

## Key benefits

* **Shoppers hear about the moments that matter.** Standard triggers cover the full journey: order and fulfilment updates, pick-up, in transit, out for delivery, delivered, failed attempts, delays, customs, collection points and return to sender.
* **One trigger, several channels.** Each notification configuration sends on email, SMS or webhook. Klaviyo is available as a further channel through the integration.
* **No duplicate messages.** When several triggers match the same event, only the highest-priority trigger sends.
* **Templates carry shipment data.** HTML email templates use field placeholders that are filled from the shipment at send time, and campaigns can be placed in emails the same way.
* **You see what was sent.** The notifications overview reports sent, open and click rates per configuration, and each shipment keeps a history of the notifications sent for it.

## How it works

### Notification configurations

A notification configuration combines a channel, a trigger, a template (for email) or an endpoint (for webhook), optional shipment filters and the recipients. The overview table lists every configuration with its name, channel, trigger, tracking experience, last update, sent, open and click rates and status. You can search by name and filter on channel, status, sender, recipients, carrier, tracking experience, tag, trigger and template.

| Status | Meaning |
| - | - |
| Draft | Nothing is sent. Every field can be edited. The trigger can only be changed in this status. |
| Active | Notifications are sent for the trigger. Deactivate before editing. A configuration cannot return to Draft once activated. |
| Deactivated | Nothing is sent. Every field except the trigger can be edited. |
| Archived | Hidden from the overview. |

Deactivating a trigger deactivates every notification configuration that uses it. Reactivating the trigger does not reactivate them.

### Triggers

Triggers define when a notification is sent and apply to every channel. The standard triggers fall into these groups:

| Group | Examples |
| - | - |
| Order and fulfilment | Order confirmation, order updates, packing confirmation, fulfilment updates |
| Carrier handover | Shipment confirmation (carrier pre-alert), shipment pick-up, in transit |
| Delivery | Out for delivery, successfully delivered (all events, doorstep, neighbour, left at the door) |
| Collection points | Dropped off at a parcel locker, parcel shop or post office; collection reminders after 12, 24, 48 and 72 hours; successful collection |
| Exceptions | Failed delivery attempt (not at home, wrong address, addressee unknown, address issues, once a day), shipment delayed (pick-up, transport, delivery, processing error), customs issues and payment issues, shipment cancelled, shipment damaged |
| Inactivity | No updates detected for 24, 36, 48, 60 or 72 hours |
| Return to sender | Return to sender shipment, returned successfully |
| Feedback | Delivery feedback 2, 12 or 24 hours after delivery |
| All events | Every event in the journey, most often used for webhooks |

Return triggers (request submitted, approved, rejected, drop-off reminders, carrier booking, quality check, refund and return shipment events) are covered on [Returns Notifications & Refund Triggers](https://developers.perform.ai/products/returns/returns-notifications-and-refund-triggers.md).

Two rules apply to every trigger:

* **Trigger priority.** When more than one trigger matches the same tracking event, only the highest-priority trigger sends. Lower-priority triggers are suppressed for that event.
* **Carrier events only.** Only tracking events received from the carrier trigger notifications. Events added to a shipment manually or through the events API are stored in the shipment’s history but do not send a notification.

Time-based triggers such as collection reminders, no-update alerts and delivery feedback may need to be enabled for your account by your account team.

### Channels

| Channel | How it works |
| - | - |
| Email | Sent to the recipient email on the shipment, or to other addresses you add. Uses an HTML template. Sender name and address are set per configuration. |
| SMS | Sent to the phone number on the shipment in international format, for example `+6591234567`, or to other numbers you add. Uses the default SMS body. SMS sending is available once the connection to the SMS provider is set up for your account. |
| Webhook | Sent to a webhook endpoint configured under **Settings**, authenticated with HMAC. Your account has one endpoint by default; more can be enabled by your account team. Payload formats are documented in the API reference. |

### Templates and field placeholders

Email templates are HTML. Start from the sample template or add your own, preview it for a tracking number on desktop and mobile, and save it. Field placeholders insert shipment data such as the tracking number, carrier or estimated delivery date; search for the placeholder in the editor, copy it and paste it into the template. A placeholder only shows data that exists on the shipment, and all dates and times in placeholders are in UTC. Campaign placeholders place a Campaign Manager banner in the email.

### Shipment filters and recipients

Each configuration can be limited to shipments from a carrier, a tracking experience or shipments carrying a tag. By default the parcel recipient on the shipment is notified. **Notify other** sends the notification to additional email addresses or phone numbers instead of or as well as the recipient, which is also the way to test a configuration.

### Reporting

The notifications overview shows cumulative sent, open and click figures per configuration, with the last 14 days at the top. The dashboard refreshes once a day at 00:05 UTC and cannot be filtered by channel or trigger; use **Reports & Analysis** for that.

| Metric | Definition |
| - | - |
| Unique opened rate (email) | Emails opened divided by emails sent |
| Unique clicked rate (email and SMS) | Messages with a click divided by messages sent |
| Unsubscribed rate (email) | Recipients who opted out divided by emails sent |
| Bounced rate (email and SMS) | Messages not delivered divided by messages sent |

In Shipment Overview, the **Notifications sent** column and filter show which shipments received a notification, and the bell icon on a shipment opens its notification history with the name, channel and status of each message.

## Set up in the portal

Go to **Post-Purchase** > **Notifications** and select **Add Notification**.

1. Choose the channel: email, SMS or webhook. For webhooks, first create and activate an endpoint under **Settings** > **Webhook** with a name, the endpoint URL and the HMAC key. A sample payload is sent to validate the URL before saving.
2. Name the notification (up to 32 characters) and select the trigger.
3. For email, select a template: the sample template, your own HTML template, or the premium template available with the Tracking Page. For webhook, select the endpoint.
4. Optionally filter the shipments by carrier, tracking experience or tag.
5. Choose who is notified: the parcel recipient (default) or other addresses or numbers under **Notify other**.
6. Select **Next**, then **Save**, then **Activate**.

To manage templates, go to **Post-Purchase** > **Notification template**, open the sample template or select **Add template**, edit the HTML, preview it and save.

## Use via API and MCP

* Webhook payload formats: [Shipment update v5.0](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-0.md), [v5.2](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-2.md) and [v5.3](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-3.md). Set-up is in the [Webhooks guide](https://developers.perform.ai/guides/webhooks.md).
* Recipient details come from the shipment: set `notification_email` and `notification_phone` when you [create a shipment](https://developers.perform.ai/guides/create-shipment.md). See the [Notifications guide](https://developers.perform.ai/guides/notifications.md).
* MCP tools: `list_notification_configs` lists your configurations and `list_notification_triggers` lists the triggers available to your account. See [MCP tools](https://developers.perform.ai/mcp/tools.md).

## FAQ

### Why did a shopper get two messages for one event?

Two configurations with triggers of the same priority matched the event, or two channels are active for the same trigger. Within one channel, only the highest-priority matching trigger sends.

### Why was no SMS sent?

The shipment has no phone number, or the number is not in international format. SMS also requires the SMS provider connection to be set up for your account.

### Can I send notifications for events I add through the API?

No. Only tracking events received from the carrier trigger notifications. Events added manually or through the events API are stored but do not send.

### How do I test a notification without emailing a shopper?

Use **Notify other** with your own email address or phone number, activate the configuration, and deactivate it after the test.

### Why does a placeholder show up empty?

The shipment does not carry that field. Placeholders only render data that exists in the shipment payload.

### Can I change the trigger on an active notification?

No. The trigger can only be changed while the configuration is in Draft. Create a new configuration for the new trigger.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Nothing is sent | The configuration is in Draft or Deactivated, or its trigger was deactivated | Activate the configuration. If the trigger was deactivated and reactivated, activate each configuration again. |
| Webhook endpoint cannot be saved | The endpoint URL did not accept the sample payload | Make the URL publicly reachable and return a success status for the sample payload, then save again. |
| Email dates are off by a few hours | Placeholder dates and times are in UTC | Tell shoppers the timezone, or use the Tracking Page link for local times. |
| Open and click rates look stale | The dashboard refreshes once a day at 00:05 UTC | Check again after the next refresh, or use **Reports & Analysis**. |
| Notification links open the wrong Tracking Page | The shipment is linked to another tracking experience | Set `tracking_page_reference` on the shipment. |

## Related

* [Tracking Page](https://developers.perform.ai/products/post-purchase/tracking-page.md)
* [Campaign Manager](https://developers.perform.ai/products/post-purchase/campaign-manager.md)
* [Returns Notifications & Refund Triggers](https://developers.perform.ai/products/returns/returns-notifications-and-refund-triggers.md)
* [Webhooks](https://developers.perform.ai/products/integrations/webhooks.md)
* [Klaviyo](https://developers.perform.ai/products/integrations/klaviyo.md)
* [Post-Purchase overview](https://developers.perform.ai/products/post-purchase/overview.md)


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