Retainer Management
For agencies with ongoing client relationships, retainers are the most predictable revenue model. ACOS tracks each retainer's monthly hour budget, rolls unused hours forward (if configured), and generates invoices with one click.
What a Retainer Is
A retainer is a recurring monthly engagement where a client pays a fixed fee for access to a set number of hours per month. Unlike project billing (where you invoice after completing work), retainers are invoiced at the start of each period regardless of how many hours are used.
In ACOS, a retainer links a project (where the work happens and time is logged) to a client contact, defines the monthly terms, and automatically creates a RetainerPeriod record at the start of each month.
Retainer Management is available on the Growth and Scale plans. Starter plan users can track retainer work using regular projects and time-and-material invoicing, but the automated period tracking and consumption bars are not available.
Core Concepts
| Concept | Definition |
|---|---|
| Retainer | The master record: links project to contact, sets monthly_hours, monthly_rate, rollover policy, and active dates. |
| Retainer Period | One record per calendar month per retainer. Tracks hours_budgeted, hours_used, hours_carried_over, and the invoice for that month. |
| Rollover Policy | Controls what happens to unused hours at month-end. Three options: No rollover (hours expire), Carry forward (unused hours added to next month's budget), or Carry forward capped (same as carry, but capped at one month's base budget so the buffer can never grow beyond 2× the monthly hours). |
| Overage | When hours_used exceeds hours_budgeted in a period. ACOS alerts you but does not block time logging. How to handle overage is a commercial decision. |
Setting Up a Retainer
Create a project for the retainer
The project is where team members will log their time. Set the project type to 'Retainer'.
Go to Finance → Retainers → New Retainer
The retainer form opens.
Fill in the retainer details
Name (e.g. 'Acme Corp — Monthly Retainer'), link to the project and client contact, set monthly hours (e.g. 40h), monthly rate (e.g. $4,000), start date, and optionally an end date.
Choose a rollover policy
No rollover: unused hours expire at month-end. Carry forward: unused hours are added to next month's budget. Carry forward (capped): same as carry, but the carried hours cannot exceed one month's base budget — preventing the buffer from growing indefinitely.
Save
ACOS creates the first RetainerPeriod immediately (for the current month). From now on, a new period is created automatically on the 1st of each month.
Monthly Period Automation
On the 1st of every month at 00:01, ACOS runs a background task that creates a new RetainerPeriod for every active retainer. This happens automatically — you don't need to do anything.
No rollover
Previous period: 40h budgeted, 34h used → 6h unused (expire)
New period: 40h budgeted (always the monthly base)
Carry forward
Previous period: 40h budgeted, 34h used → 6h unused
New period: 40h (monthly) + 6h (carried over) = 46h budgeted
Note: if the client takes a very light month, the buffer can grow indefinitely.
Carry forward (capped)
Monthly base: 40h. Cap = 40h (one month's base).
Previous period: 40h budgeted, 10h used → 30h unused
Carry = min(30h, 40h cap) = 30h → New period: 70h budgeted
If previous carry was already 40h: carry capped at 40h → New period: 80h max
Live Hour Consumption Tracking
Every time a team member logs time on the retainer's linked project, ACOS automatically updates the current period's hours_used. This happens via a background signal triggered on every time entry save or delete.
The consumption bar
A RetainerConsumptionBar appears on:
- The project card on the project list (for retainer-type projects)
- The Retainer List page in the usage column
- The Retainer Detail page in the current month card
Color coding: green below 80%, amber 80–100%, red above 100% (overage). Overage is shown as a bar extending past the right edge with the overrun hours displayed.
Overage alerts
When hours_used exceeds hours_budgeted, ACOS creates a Smart Alert of type retainer_overage. You'll see it on the Dashboard. ACOS does not block time logging — the decision about how to handle overage with the client (charge extra, absorb it, credit next month) is yours.
Generating a Monthly Invoice
Retainer invoices are not generated automatically. A Manager or Admin must trigger each invoice manually. This is intentional — you may need to adjust the invoice before sending (e.g. if there was overage that the client agreed to pay for).
Go to Finance → Retainers and open the retainer
The Current Month card shows hours used vs budgeted and a Generate Invoice button.
Click Generate Invoice
The RetainerInvoiceModal opens showing: the period (e.g. June 2026), hours used, and a preview of the invoice line item.
Review and confirm
The line item is pre-filled: '{Retainer name} — {Month Year}', quantity 1, rate = monthly_rate. Set the issue date and due date. Click Create Invoice.
The invoice is created in Draft status
You are redirected to the invoice detail. Review, add additional line items (e.g. overage charges), and send when ready.
The Generate Invoice button is disabled if an invoice already exists for the current period (in any status). You cannot create two invoices for the same period. If you need to void and recreate, cancel the existing invoice first.
Retainer Detail View
The Retainer Detail page (/finance/retainers/{id}) gives you a full history of the engagement:
| Section | What it shows |
|---|---|
| Current month card | Live hours used / budgeted, progress bar, Generate Invoice button |
| Period history table | One row per month: period date, hours budgeted, hours used, hours carried over, invoice status with link |
| Details card | Monthly rate, monthly hours, start/end dates, status badge, rollover policy (No rollover / Carry forward / Carry forward capped), carried-over hours for the current period |
Ending a Retainer
To end a retainer, set an end date on the retainer record. The Celery task that creates monthly periods checks the end date and will not create new periods after it. The retainer status becomes "ended" automatically.
Ending a retainer does not affect the linked project or any existing invoices. The project continues to exist and can still have time logged against it. Only the automatic period creation and consumption tracking stop.
Roles & Permissions
| Action | Member | Manager | Admin | Owner |
|---|---|---|---|---|
| View retainers | ✗ | ✓ | ✓ | ✓ |
| Create/edit retainers | ✗ | ✓ | ✓ | ✓ |
| Generate retainer invoices | ✗ | ✓ | ✓ | ✓ |
| Delete retainers | ✗ | ✗ | ✓ | ✓ |
Best Practices
- Create the retainer at the same time as the project — don't add it weeks into an engagement, as you'll have existing time entries that won't be tracked against a period.
- Use rollover hours if your client agreement allows it. Rollover reduces friction — clients feel they're getting value even in lower-activity months.
- Invoice retainers at the beginning of the month, not the end. Retainer billing is for access to capacity, not for work delivered — invoice upfront.
- Review the consumption bar weekly. If hours are running out with two weeks left in the month, notify the client proactively before you hit overage.
- Always generate the retainer invoice before the regular project invoice in the same month. The retainer invoice captures the monthly fee; the project invoice should only include any billable overage.
FAQ
Can I have multiple retainers on the same project?
No. Each retainer links to one project. If you need to track different client retainers, create separate projects (e.g. 'Acme Corp — Content Retainer' and 'Acme Corp — Dev Retainer').
What if I start a retainer mid-month?
The first RetainerPeriod is created when you save the retainer. If it's the 15th of the month, the first period will have hours_budgeted = monthly_hours (the full amount, not prorated). You'll need to manually adjust the period's hours_budgeted if you want to prorate the first month.
I accidentally created a retainer period invoice for the wrong month. Can I fix it?
Cancel the invoice (this preserves the audit trail) and generate a new invoice from the correct period. If the wrong period's invoice has already been sent, you'll also need to issue a cancellation notice to the client.
Do retainer hours count toward the team utilization report?
Yes. Time entries on retainer projects count toward billable hours in the utilization report exactly like any other project. The retainer distinction only affects the period tracking and invoicing flow.