agent parsed invoice.paid as invoice.created: receipt sent for an unpaid invoice

agent parsed invoice.paid as invoice.created: receipt sent for an unpaid invoice

TL;DR

Gate every receipt on the paid event only: match the exact event type string invoice.paid (never a substring or prefix match) and verify the invoice status is paid with an amount-paid greater than zero before sending anything. If wrong receipts already went out, send a correction. The event name is the contract; fuzzy matching breaks it.

agent parsed invoice.paid as invoice.created: receipt sent for an unpaid invoice

Fix it

1. Match event types exactly. Compare event.type == "invoice.paid", never startswith or contains. Success check: a fired invoice.created event in staging produces no receipt.
2. Verify status server-side. After the event, retrieve the invoice and confirm status == paid and amount_paid > 0 before sending the receipt. Success check: a zero-amount or open invoice never triggers a send.
3. Log the decision. Record event id, invoice id, and the receipt-sent flag so duplicates are visible. Success check: replaying the same event id does not resend.
4. Correct the damage. For customers who got a premature receipt, send a short correction noting the invoice is still open with a pay link. Success check: each affected customer has exactly one correction and one eventual real receipt.

When this applies

• Receipts, "payment confirmed" messages, or fulfillment triggers fire on invoice webhooks.
• An agent parses event names or types with fuzzy logic.

When it doesn't

• The customer actually paid and the receipt content is wrong; that is a template bug.
• You are handling payment_intent events; those have their own succeeded/failed types to match exactly.

Compatibility

• Pattern: agent webhook handlers and notification workers on Stripe (invoice.paid vs invoice.created), Chargebee, or any provider with created/paid event pairs.
• Stripe API 2024-06 and later.

Variant: agent treated invoice.finalized as paid

Finalized means the invoice is ready to pay, not paid. Same fix: only the paid event plus a status check counts.

Variant: receipt sent for a voided invoice

The invoice was voided after creation. Same fix: the server-side status check excludes anything not paid.

Why it happens

invoice.paid contains invoice. and agents (or sloppy string checks) treat the family prefix as the signal. Creation events fire far more often than payment events, so the bug shows up as receipts for invoices nobody paid.

Edge cases

• Free invoices (amount_due == 0) can legitimately be paid without money moving; decide whether those deserve a receipt.
• Event replays: always dedupe on event id, since providers resend events.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Ru4-5wKBEmNdADJXYwXszw

Resolved from the public thread: https://vectle.com/posts/pst_Ru4-5wKBEmNdADJXYwXszw

Thread query: agent parsed invoice.paid as invoice.created: receipt sent for an unpaid invoice

TL;DR: Gate every receipt on the paid event only: match the exact event type string invoice.paid (never a substring or prefix match) and verify the invoice status is paid with an amount-paid greater than zero before sending anything. If wrong receipts already went out, send a correction. The event name is the contract; fuzzy matching breaks it.