A credit note at the payment provider is invisible in the console, even when it settles an invoice #152

New Issue

2026-09-28T04:19:17Z

cgalo5758 commented

2026-09-28 04:19:17 +00:00

In Stripe, a credit note is how a finalized invoice is corrected. On an open invoice it lowers the amount due, and a credit note for the full remainder moves the invoice to paid. On a paid invoice it refunds the member or credits their customer balance. The console routes no credit_note.* event and has no entity for one, so an operator who issues a credit note in Stripe sees an invoice change status or amount with no record of why.

What exists today

Events. The Stripe webhook routes invoice.finalized, invoice.paid, invoice.payment_failed, invoice.voided, customer.* and customer.subscription.* only.
Read-back. The console reads each invoice back from Stripe, so an invoice a credit note settles is still recorded as paid. The rule "a paid invoice without a charge is recorded with one succeeded payment of amount_paid" then applies, with nothing to show the credit note. What amount_paid holds in that case is unconfirmed.
Design. design/ names credit notes as the only correction to a finalized invoice but has not designed the entity. It says "Credit notes are not yet modeled in the schema". It leaves open whether they are platform documents or the provider's. It defers discount reversal on credit notes until then.

What depends on it

What a member sees on an invoice a credit note changed: the original amount, the credit, and what remains.
Refunds (#106), discounts (#25) and credit balance (#27), each of which a credit note touches.
Numbering, if the platform ever issues its own credit notes: they need their own sequence (design/ leaves this open).

In Stripe, a credit note is how a finalized invoice is corrected. On an open invoice it lowers the amount due, and a credit note for the full remainder moves the invoice to paid. On a paid invoice it refunds the member or credits their customer balance. The console routes no `credit_note.*` event and has no entity for one, so an operator who issues a credit note in Stripe sees an invoice change status or amount with no record of why. ## What exists today - **Events.** The Stripe webhook routes `invoice.finalized`, `invoice.paid`, `invoice.payment_failed`, `invoice.voided`, `customer.*` and `customer.subscription.*` only. - **Read-back.** The console reads each invoice back from Stripe, so an invoice a credit note settles is still recorded as paid. The rule "a paid invoice without a charge is recorded with one succeeded payment of `amount_paid`" then applies, with nothing to show the credit note. What `amount_paid` holds in that case is unconfirmed. - **Design.** `design/` names credit notes as the only correction to a finalized invoice but has not designed the entity. It says "Credit notes are not yet modeled in the schema". It leaves open whether they are platform documents or the provider's. It defers discount reversal on credit notes until then. ## What depends on it - What a member sees on an invoice a credit note changed: the original amount, the credit, and what remains. - Refunds (#106), discounts (#25) and credit balance (#27), each of which a credit note touches. - Numbering, if the platform ever issues its own credit notes: they need their own sequence (`design/` leaves this open).

cgalo5758 added the

kind

design

area/billing area/integrations labels 2026-09-28 04:19:17 +00:00

cgalo5758 referenced this issue from a commit

2026-10-02 00:49:58 +00:00

Read invoices back from Stripe and archive the change

Sign in to join this conversation.