---
id: financeiros/safras-permanencia
industry: Financial services
usage: common
effort: medium
grain: Customer x calendar month (complete grid), with vintage and MoB; contract for retention
---

# Vintages and retention

How each vintage of borrowers, cooperative members or contracts behaves month by month: who keeps paying, how much it earned, how much went past due and how long it stays, comparing vintages at the same age.

## Executive summary

**For:** Lending and earned-wage-access fintechs, vehicle protection cooperatives and associations, funding platforms and firms with recurring revenue.

**What it solves**

- Each vintage is compared with the others at the same age, without mixing new and old vintages.
- Vintage revenue, active customers and delinquency come from what was paid and what fell due, not from what was billed.
- Average retention is no longer pushed up by those who are still active.

**Why it matters:** In lending and protection, the result of today's decision only shows up months later. The vintage curve shows whether the new credit policy, channel or price improved the book before the monthly total makes it obvious. Without the same yardstick for start, end and revenue, each team compares vintages its own way and the discussion is about the number, not the decision.

**Business questions it answers**

- What is revenue by MoB for the January vintage compared with October's?
- How many borrowers from last quarter's vintage are still active in month three?
- Which vintage has the most past-due amount at the same age?
- What is the average retention of members who left, by region?
- What is realized LTV by region and by product type?
- Did the new channel bring a better or worse vintage than average?

**What you need**

- The payments source connected to Nekt: lending core, subscription invoices or protection core invoices
- The start and end rules agreed with the business: which payment opens the vintage and which status closes it
- The first version of each customer's record (score, channel, employer) or a history starting now

**What you get**

- A customer x month table with vintage, MoB, active flag, revenue and past due
- Vintage curves ready to compare at the same age
- Retention per contract and realized LTV by region and product
- An AI agent that answers about vintages with the start and end rules

## Detailed

### The problem

The contracts table says when each customer joined by sign-up date, not by first payment, and the current status rewrites the score and channel at entry. Whoever sums by calendar month mixes vintages of different ages. Whoever computes retention up to today for active customers and up to the last update for inactive ones gets an average that rises on its own and leaves out exactly those who canceled.

### Business rules

1. **The vintage is the first real money.** Vintage = month of the first confirmed payment: first paid subscription invoice, first disbursed advance or first paid monthly fee of the contract. Sign-up, proposal or contract signing date does not open a vintage, because some people sign up and never pay. State the rule in the context document and check that the code uses the same one. (Avoid: Vintage by user or contract creation date.)
2. **Vintage attributes frozen at entry.** Score, risk tier, channel, campaign and employer used to slice the curve come from the first version of the record (the oldest by update date) or the version valid on the entry date in the history. The current record changes later: the score goes up, the channel gets corrected. (Avoid: Slicing the vintage by the customer's current score.)
3. **Complete customer x month grid.** Generate one row per customer and calendar month since the vintage, with zero where there was no payment. MoB = months between the vintage and the month. Months before the vintage and customers with a deleted account are flagged (MoB -1) and left out of the curves. (Avoid: Using only the months when the customer paid, and watching the curve rise when they disappear.)
4. **One customer, several accounts.** The same customer may have more than one account or contract. The curve is per customer (master id or tax ID), adding all accounts; the account shown is the first one. Subscription and advances may have different vintages: keep one MoB per product and say which one the curve uses. (Avoid: One vintage per account, counting the same customer twice.)
5. **Vintage revenue is what was paid.** Add only amounts actually paid: invoice with success status, fee with confirmed payment, amount collected on the advance. An open invoice is not revenue, not even when the paid amount is zero and the billed amount is filled. In protection, use only the monthly fee (monthly invoice type), without canceled invoices. A repeated invoice in the same month for the same subscription counts once. (Avoid: Using the billed amount when the paid amount is zero.)
6. **Vintage delinquency: past due, not upcoming.** In the reference month, separate what fell due and was not paid (collection date before today with an error or partial payment) from what is awaiting payment (collection in the future). Only past due enters vintage delinquency. Vintage delinquency at MoB k is the past-due unpaid amount / amount disbursed to the vintage, and the migration between buckets from one month to the next is the roll rate. (Avoid: Counting as delinquent everything unpaid, including what falls due next week.)
7. **The end comes from a stated status.** State which statuses close a customer (for example, inactive, canceled and canceled with pending items) and use the date of the change to that status. In subscriptions, end = cancellation, or the last paid month if later. Delinquent is not an end until it becomes canceled. Every final status counts: leaving plain canceled out removes exactly those who left. (Avoid: Treating only some statuses as an end and using the contract's last update as the exit date.)
8. **Active customers have no closed retention.** Whoever is still active has open retention. Average retention is computed only among closed contracts, or with a survival curve (percentage still active in each month since entry). Never mix closed contracts with active ones measured up to today. (Avoid: Average days active using today as the end for those who remain.)
9. **Compare vintages at the same age.** Compare MoB 3 of one vintage with MoB 3 of the others. Only customers who have had time to reach a MoB enter its denominator. The current month's vintage has not closed its first month yet. Churn in a rolling window (exits in the last 30 and 90 days) is another metric, recomputed on every run, and does not replace the curve. (Avoid: Comparing the total cumulative revenue of a 2-month vintage with a 12-month one.)

### What opens and what closes the vintage, by business

Rules real operations used. Pick one per product and write it in the context document.

- **Advances and lending** → Opens at the first disbursed advance (`closes: deleted account or stated inactivity`)
- **Lending app subscription** → Opens at the first paid invoice (`closes: cancellation or last paid month, whichever is later`)
- **Protection and cooperative** → Opens at the contract's first payment (`closes: inactive, canceled or canceled with pending items`)
- **Real estate funding** → Opens at the first contracted or completed contribution (`closes: last buyback`)
- **Accounting and BPO firm** → Opens at entry into the customer journey pipeline (`closes: churn stage; milestones: handoff and ongoing`)
- **Deleted** → Out of every vintage (`deleted in the CRM or deleted account`)

### Definitions

| Metric | Definition |
|---|---|
| Vintage | month of the customer's first confirmed payment in the product |
| MoB (months on book) | difference in months between the vintage month and the reference month; MoB 0 is the vintage month itself |
| Vintage active customers at k | vintage customers with a confirmed payment or active contract at MoB k / vintage customers who have reached MoB k |
| Vintage revenue at k | sum of amounts paid by the vintage's customers at MoB k; cumulative adds 0 to k |
| Vintage delinquency at k | past-due unpaid amount at the end of MoB k / amount disbursed to the vintage, excluding upcoming amounts |
| Retention | days between the contract start date and the date of the change to a final status; only for closed contracts |
| Realized LTV | sum of monthly fees paid per contract, aggregated by region or product, without canceled or open invoices |
| Rolling-window churn | customers and recurring revenue with an exit in the last 30 or 90 days / active customers at the start of the window, recomputed on every run |

### Pitfalls

- **The documentation says one thing, the code does another.** The context document defined the vintage as the month of the first advance, but the table used the user's sign-up date, and the agent answered with the wrong rule. How to avoid: Check the vintage column against the first payment on a sample before publishing.
- **An average that rises on its own.** Retention used today as the end for active customers, and the average grew by one day every day with nobody leaving or joining. How to avoid: Retention only of closed contracts and a survival curve for the base.
- **Those who canceled disappeared.** Retention treated only inactive and canceled with pending items as an end; plain canceled contracts were left out of the calculation. How to avoid: A closed list with every final status.
- **LTV with open invoices.** When the paid amount came as zero, the sum used the billed amount, and LTV counted monthly fees that were never paid. How to avoid: Add only invoices with confirmed payment.
- **Today's score on yesterday's vintage.** The vintage was sliced by the customer's current score, and the risk tier at entry looked better than it was. How to avoid: Use the first version of the record or the one valid on the entry date.
- **Deleted deal in the curve.** Deals deleted from the CRM stayed in the customer journey vintages and created churn that did not happen. How to avoid: Filter out deleted records before building the vintage.

### Acceptance test

- [ ] Each customer has exactly one row per month since the vintage, with no gaps and no months before it in the curves.
- [ ] The vintage of 5 randomly chosen customers equals the month of their first confirmed payment in the source.
- [ ] Total grid revenue for a closed month matches confirmed billing payments in the same month (difference below 1%).
- [ ] No active contract enters average retention; every contract with a final status does.
- [ ] The denominator of each MoB only has customers from vintages that have already reached it.

### Context document

```text
Vintages and retention
- Table: <grid_table>, one row per customer and calendar month, with vintage, MoB, active flag, paid revenue and past-due amount.
- Vintage = month of the first confirmed payment in product <product>. Do not use sign-up or contract date.
- Vintage attributes (score, channel, campaign, employer) are those at entry, not the current ones.
- MoB 0 is the vintage month. Rows with MoB -1 (before the vintage or deleted account) stay out of the curves.
- Revenue = confirmed payments only. Open, canceled or zero-paid invoices are not revenue.
- Vintage delinquency = past-due unpaid amount / amount disbursed. Upcoming amounts are not delinquency.
- Final statuses: <inactive, canceled, canceled with pending items>. End date = date of the status change. Delinquent is not an end.
- Average retention only with closed contracts. For active customers, use the survival curve.
- Always compare vintages at the same MoB and only with vintages that have already reached it.
Exceptions per client:
- <client>: customer with several accounts consolidated by id <master_id>; the account shown is the first one.
- <client>: funding vintage per development, from the first contribution to the last buyback, only contracted or completed operations.
```

### Variations

- **Vintage by campaign:** Slice the curve by the install or lead campaign and partner to compare each channel's return at the same MoB.
- **Roll rate by vintage:** Migration of amounts between past-due buckets from one month to the next, broken down by vintage, to anticipate provisioning.
- **Partner vintages:** In funding and B2B, the vintage belongs to the partner (developer, firm) and measures tenure, first contribution and last buyback.