Report a Refund

POST /siren/v1/event/refund

Creates a RefundTriggered event for a previously reported sale. The original transaction is located through Siren’s mapping table using the external ID and source — there’s no need to know the Siren transaction ID. Used alongside POST /event/sale for headless commerce integrations that need to clean up conversions and obligations when an order reverses.

Request Body:

Field	Type	Required	Description
source	string	Yes	Same identifier used when the sale was reported (e.g., "shopify"). Combined with externalId to find the original transaction via the mapping table.
externalId	string	Yes	The order or transaction ID that was refunded — must match the value passed when the sale was originally reported.

Example Request:

POST /wp-json/siren/v1/event/refund
Content-Type: application/json

{
  "source": "shopify",
  "externalId": "ORD-1004"
}

Example Response:

HTTP/1.1 200 OK

Empty body on success.

If no transaction can be found for the given external ID and source, returns 404 with the request fields echoed in the error body. This typically means either the sale was never reported through /event/sale, the IDs don’t match, or the original sale belonged to a different source value.

Internally this fires RefundTriggered, which traverses the conversion pipeline in reverse: linked conversions are rejected, obligations are cleaned up, and any associated payouts are flagged for review. See How Refunds Work for the full lifecycle.