Action guide
A paper trail for every invoice your billing provider settles
POST
/v1/events · invoice.paidEmit an `invoice.paid` event from your Stripe (or other provider) webhook handler. Store the amount, currency, provider event id and the customer's organization.
When to emit
Inside the webhook handler that processes the `invoice.payment_succeeded` event from your billing provider. Always emit after your own DB write succeeds.
Example payload
await recalled.events.create({
action: "invoice.paid",
actor: { id: user.id, email: user.email },
organization: user.organizationId,
metadata: {
amount: "value",
currency: "value",
providerEventId: "value"
},
});Metadata to include
Keep metadata flat and consistent across your service so it plays well with search and CSV exports.
| Key | Purpose |
|---|---|
amount | Amount in smallest currency unit (cents) |
currency | ISO 4217 code, usd, eur, gbp |
providerEventId | Stripe evt_xxx or equivalent |
invoiceNumber | Your own internal invoice number |
Suggested retention
Keep for 5 to 10 years depending on your jurisdiction's accounting requirements.