Collection and dunning

Collection is how Ownrecord gets an issued invoice paid. A subscription collects in one of two ways:

• charge_automatically: the customer's saved payment method is charged. If the charge is declined, dunning retries it on a schedule.
• send_invoice: the invoice is emailed with your bank details and a due date. Reminders follow, and an invoice still open well after its due date puts the subscription past due.

Each brand sets how this works in Brand → Settings → Billing (or brands.update with billingSettings).

Dunning: when a card payment fails#

When a charge of an open subscription invoice is declined:

1. The subscription becomes past_due and subscription.past_due and invoice.payment_failed are sent. The customer gets an email with a link to pay the invoice now.
2. The charge is retried 1, 3, 5 and 7 days after the first failure (the brand's dunning.retryOffsetsDays). Each failed retry emails the customer again with the date of the next one.
3. When the customer changes their payment method (a new default card), the invoice is retried at once. The scheduled retries stay where they are.
4. Hard declines stop the retries: a card reported lost or stolen, or refused with do_not_honor twice. The customer is asked to pay with another card. A new card still gets its immediate retry until the last scheduled date.
5. After the last retry, the brand's final action applies: unpaid (the default) keeps the subscription with its features off and issues no new invoices, or canceled ends it. The open invoice stays payable either way.

If a renewal (or the end of a trial) finds no usable payment method, its invoice stays open and dunning starts the same way, with nothing charged: the customer is asked to pay the invoice, the scheduled retries find no card until one is saved, and saving a new default card retries at once.

Paying the open invoice, by card, through the hosted invoice page, by marking it paid or from a bank statement, makes a past_due or unpaid subscription active again and sends subscription.recovered.

Retries are safe to repeat: each charge has its own idempotency key ({invoice}:charge:{attempt}), and a charge is never made while the previous one's outcome is still on its way (at most 24 hours).

Features while past due#

While a subscription is past due, its entitlements stay on until entitlementGraceUntil: the failure plus the brand's entitlementGraceDays (7 by default). After that they turn off, even if retries are still running. An unpaid subscription grants nothing.

Bank-transfer invoices: reminders and overdue#

An open send_invoice invoice gets reminders on the days of your legal entity's time zone:

Every reminder repeats the amount due, your bank details and the payment reference (the invoice number), with a link to pay by card. A reminder whose day is before the invoice was issued is skipped.

When the invoice is still open after its due date plus the brand's sendInvoice.graceDays (14 by default), it is overdue: invoice.overdue is sent, and an active subscription becomes past_due with the same grace for its features. Nothing is charged; after the last day of the retry schedule the final action applies, as for cards.

Bank statements#

Import your bank account's statements (Entity → Ledger → Bank statements, or POST /api/v1/bank_statements/imports) as CSV. A file needs a header row and, for each booked transaction, a booking date, a signed amount (incoming money is positive) and the reference; the payer's name and a currency column are optional. Common column names in English, German and Croatian are recognised; otherwise name the columns.

Each incoming transfer is matched to the entity's open invoices, across all its brands:

• Exact match: the reference contains the number of exactly one open invoice, and the amount is that invoice's amount due. The invoice is marked paid on the booking date (Dr bank / Cr receivables in the ledger).
• Review: everything else waits in the review queue with the reason: another amount than the invoice's (amount_mismatch), several invoice numbers (ambiguous_reference), no number but invoices with exactly this amount due (amount_only), or no match at all. Match a line to the invoice it pays (bank_statements.lines.match; the amounts must be equal) or ignore it with a reason.

Invoices are paid in full only: a partial payment stays in review until you settle it with the customer. The same file can't be imported twice, and lines of an overlapping statement that were imported before are skipped. CAMT.053 files arrive in a later version.

The hosted invoice page#

Every invoice email and reminder links to the invoice's hosted page: the amounts, the due date, your bank details with the payment reference, the PDF, and payment by card while the invoice is open. The card payment is one-off (no card is saved). A card the customer tries there and that is declined doesn't count as a dunning retry.

Card-expiry reminders#

30 days and 7 days before a saved card expires, the customer gets an email when a subscription that charges the card renews after that date. Turn it off with the brand's cardExpiryReminders.

Test clocks#

For customers on a test clock, collection runs when the clock moves forward, in time order with renewals and each step at its own time: dunning retries and the final action, bank-transfer reminders and overdue, and card-expiry reminders. The real-time schedule leaves them alone. A card payment or decline of a clock's invoice, and a new default card, are recorded at the clock's time; a bank statement import pays on the booking date.