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

# Returns Notifications & Refund Triggers

> Keep shoppers and your team informed through the return journey, and start refunds from return events through webhooks.

**Available to all Returns customers.**

## Summary

Returns Notifications adds a Customer Initiated Returns trigger category to the Notification Center, with return-specific field placeholders and pre-filled templates, so shoppers hear from you at every step from request to refund. Refund Triggers use the same events to send a webhook to your systems at the moment you choose to start a refund, for example when the carrier scans the parcel or when your warehouse finishes the quality check.

## Who it’s for

Customer service teams who want fewer “where is my refund” tickets, and operations or finance teams who want the refund to start from a tracked event rather than from a manual check. Perform.AI does not process refund payments; it tells your systems when to.

## Key benefits

* **Shoppers are told what happens next.** Event-based and time-based triggers cover the return journey, including reminders to drop off a parcel and updates when the carrier picks it up or delivers it back to you.
* **Templates are ready to send.** Every return trigger comes with a pre-filled HTML template that already carries the relevant field placeholders. Edit it or use it as is.
* **Messages carry the return details.** Field placeholders insert return data, collection point details and a download link for the return label or QR code.
* **Every channel you already use.** Return triggers work on email, SMS, webhooks and the connected marketing channels available in your Notification Center.
* **The refund starts from an event you choose.** A webhook fires when the carrier confirms receipt, when the parcel reaches your warehouse, or after your quality check, so your order system can refund without someone watching the tracking.

## How it works

### Return triggers

When Returns is enabled for your organisation, the Notification Center gains a trigger category named **Customer Initiated Returns** with 30 additional triggers, on top of the standard shipment triggers. The category includes:

* **Event-based triggers**, which fire on a return event such as the request being submitted, approved or rejected, the label being generated, or the return shipment being picked up, in transit or delivered back to you.
* **Time-based triggers**, which fire when a set time has passed without the next step, for example a reminder to drop off the parcel after approval.

Triggers are available for all channels: email, SMS, webhooks and the marketing channels connected to your account.

### Field placeholders

Returns adds 41 field placeholders to the ones available for outbound notifications:

| Group | What they insert |
| - | - |
| Return data | Details of the return request on the shipment, such as the items and reason. |
| Collection point | Address and opening details of the drop-off or collection point. Populated only when the carrier provides collection point data; otherwise the value is empty. |
| Document | `{{document.hyperlink_type}}` inserts a link to download a document attached to the shipment. Replace `type` with the document type, for example the return label or QR code, so the right document is linked. |

### Pre-filled templates

When you create a notification with the channel set to Email or SMS, a trigger from the Customer Initiated Returns category and the template set to Custom Template, the editor opens pre-filled with the relevant field placeholders and default branding. You can edit the content before activating.

### Internal notifications

Triggers can also notify your own team, for example an inbound pre-alert to a warehouse when returned items are out for delivery to it. Use the recipient settings on the notification to send to internal addresses.

### Refund triggers

Perform.AI does not process refund payments. It supports the refund workflow through webhooks:

1. You decide which return event should start the refund: the carrier confirming receipt of the parcel, the parcel arriving at your warehouse, or the end of your quality check.
2. Carrier events arrive through tracking. Warehouse and quality check events are ones you add to the Return Shipment with the [Create Events API](https://developers.perform.ai/guides/create-events.md).
3. A webhook notification on that event sends the shipment payload to your endpoint, and your order or payment system processes the refund.

Return events added through the API also appear in the tracking timeline of the returns widget, so the shopper sees the quality check and refund steps.

### Webhook format 5.2

Outgoing webhooks in format 5.2 carry the same data as format 5.0 plus a `returns` object, `line_items`, `collection_point`, `rating` and enriched `event.location`. Format 5.2 is enabled for your organisation automatically when Returns is enabled. See [Webhooks](https://developers.perform.ai/guides/webhooks.md) for the payload and the newer format 5.3.

### Notification settings

* A notification’s trigger cannot be changed once the notification is activated. Deactivate it first, then edit.
* Only addresses in the shipment’s `notification_email` array and numbers in `notification_phone` receive shipper-side notifications. See [Notifications](https://developers.perform.ai/guides/notifications.md).

## Set up in the portal

Go to **Returns** > **Notifications**. This is the same Notification Center as Post-Purchase, filtered to your return journey.

1. Select **Add Notification**.
2. Choose the channel, for example **Email**.
3. Pick a trigger from the **Customer Initiated Returns** category.
4. Set the sent-from and reply-to addresses, assign a template, and add filters and recipients if you need them. Choose **Custom Template** to start from the pre-filled HTML for that trigger.
5. Select **Next** and preview the subject and content.
6. Activate the notification.

For a refund trigger, repeat the steps with the channel set to **Webhook** and the trigger set to the event that should start the refund.

> [!NOTE]
>
> Once a notification is active, its trigger is locked. To change the trigger, deactivate the notification, edit it and activate it again.

## Use via API and MCP

* Add warehouse and quality check events to a Return Shipment with [Create Events](https://developers.perform.ai/guides/create-events.md).
* Receive return events on your endpoint through [Webhooks](https://developers.perform.ai/guides/webhooks.md). Payload formats: [5.2](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-2.md) and [5.3](https://developers.perform.ai/api-reference/webhooks/shipment-update-v5-3.md).
* Set notification recipients on a shipment with the `notification_email` and `notification_phone` fields. See [Notifications](https://developers.perform.ai/guides/notifications.md).
* Through the Perform.AI MCP server, your AI assistant can list your notification configurations with `list_notification_configs` and the available triggers with `list_notification_triggers`. See [MCP tools](https://developers.perform.ai/mcp/tools.md).

## FAQ

### Does Perform.AI refund my customers?

No. Perform.AI never moves money. It sends a webhook on the return event you choose, and your order, payment or ERP system issues the refund.

### Which event should start the refund?

That is your policy decision. Brands that refund early use the carrier’s pick-up or receipt scan. Brands that want to inspect the goods first add a quality check event to the Return Shipment and trigger the refund from that. For higher-value items, refund after the parcel is back in the warehouse.

### Can I send return notifications through my marketing platform?

Yes. Return triggers are available on every channel in your Notification Center, including the connected marketing channels, so you can send branded emails from your own platform based on real return events.

### Why are the collection point placeholders empty?

Collection point data has to be received from the carrier before it can be inserted. When the carrier does not provide it, the placeholder stays empty. Ask your account team whether collection point data is available for the carrier.

### Can I remind shoppers who have not dropped off their parcel?

Yes. Time-based triggers in the Customer Initiated Returns category fire when a set time has passed after approval without a carrier pick-up event, so you can send a drop-off reminder with the collection point details.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| No return triggers in the trigger list | Returns is not enabled for the organisation | Contact your account team to enable Returns. The Customer Initiated Returns category appears once it is on. |
| The trigger field is greyed out when editing | The notification is active | Deactivate the notification, change the trigger, then activate it again. |
| The label link placeholder renders empty | The `type` in `{{document.hyperlink_type}}` does not match the document type on the shipment, or the label has not been generated yet | Use the document type of the return label or QR code, and check that the Return Shipment has a document attached. |
| The refund webhook fires before the goods are inspected | The webhook trigger is set on a carrier event | Add a quality check event with the Create Events API and move the webhook trigger to that event. |
| Return fields are missing from the webhook payload | The endpoint receives format 5.0 | Switch the endpoint to format 5.2 or 5.3, which carry the `returns` object. See [Webhooks](https://developers.perform.ai/guides/webhooks.md). |

## Related

* [Self-Service Returns](https://developers.perform.ai/products/returns/self-service-returns.md)
* [Returns Overview](https://developers.perform.ai/products/returns/returns-overview.md)
* [Delivery Notifications](https://developers.perform.ai/products/post-purchase/delivery-notifications.md)
* [Returns overview](https://developers.perform.ai/products/returns/overview.md)


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