Action guide

Track every refund with its reason and amount

POST/v1/events · invoice.refunded

Emit an `invoice.refunded` event on every partial or full refund. Include the reason, customer request, accidental charge, chargeback.

Start logging for free Open the playground

When to emit

After the refund is issued through your billing provider and acknowledged in your DB.

Example payload

await recalled.events.create({
  action: "invoice.refunded",
  actor: { id: user.id, email: user.email },
  organization: user.organizationId,
  metadata: {
    amount: "value",
    currency: "value",
    reason: "value"
  },
});

Metadata to include

Keep metadata flat and consistent across your service so it plays well with search and CSV exports.

Key	Purpose
`amount`	Refunded amount in smallest unit
`currency`	ISO 4217 code
`reason`	requested_by_customer, duplicate, fraudulent, cancelled
`originalInvoiceId`	The invoice being refunded

Suggested retention

Match your accounting retention, usually 5 to 10 years.

Related actions

Log paid invoices

invoice.paid

Log payment failures

invoice.payment_failed