Invoices generated automatically, with NFe and withholdings applied.
Dedicated worker processes daily billing at 01:00 UTC. PDF, payment link, NFe and webhooks generated without manual intervention.
Feature
5
invoice states
24/7
automatic generation
PDF
natively generated
NFe
automatically linked
States modeled in InvoiceStatus
Draft
Created but not yet finalized. Can be edited (line items, values, due date).
- Next: → open (via finalize)
Open
Finalized and sent to customer. Awaiting payment. Communication schedule active.
- Next: → paid | void | uncollectible
Paid
Settled. paidAt recorded. NFe issued if nfeIssuancePolicy = on_full_payment. invoice.paid webhook fired.
- Final state (refund creates new Payment)
Void
Manually cancelled. Does not retroactively affect MRR. voidedAt + reason recorded.
- Final state
Uncollectible
Marked as revenue loss. Used in accounting write-offs. Generated by dunning after exhausting attempts.
- Final state
What you can do
Automatic Generation
Invoice-generation worker (daily 01:00 UTC) scans subscriptions with currentPeriodEnd ≤ today and generates idempotent invoices.
- Idempotency via (subscription_id, period_start)
- Reason tracked (subscription_cycle | subscription_create | manual)
- Skip of invoices in trial without card
Value Composition
Each invoice calculates subtotal + tax − discount = total. Source withholdings subtracted from net value (netValueCents).
- Discount: coupons + credits applied automatically
- Tax: ISS + others per TaxRule
- Withholdings: IRRF, CSRF, INSS, ISS withheld
Detailed Line Items
InvoiceLineItem per product/service. type distinguishes subscription, addon, usage, one-off, proration, tax, discount.
- Covered period (periodStart / periodEnd)
- Linked ServiceItem (LC 116 for NFS-e)
- Proration details in JSON when applicable
PDF Generation
Professional PDF rendered server-side via PDFKit. Customizable layout per company (logo, colors, extra fields).
- Individual or bulk download
- Signed URL with expiration
- S3 storage with path per organization
Automatic Email Delivery
Transactional email via AWS SES. Configurable templates per organization. Dynamic variables (name, amount, due date, link).
- Default template ready to use
- Free HTML/text editor
- Delivery tracking (in development)
Pre-due Reminders
Configurable communication schedule: −7, −3, −1 days and due date. Post-due until suspension.
- Email, in-app, webhook
- Pauseable per customer
- Customizable templates per event
Manual / One-off Invoice
Create one-off invoices without linking to a subscription. Useful for one-time services, adjustments, supplementary charges.
- Free line items
- Configurable due date and discount
- Same NFe and billing flow
NFe Linking
nfeIssuancePolicy defines when to issue: disabled, on_finalization, on_full_payment, per_installment.
- NFS-e via NFe.io or own provider
- Automatic retry on failures (nfe-retry worker every 30min)
- Cancellation via API
Create one-off invoice via API
bash
curl -X POST https://api.billing.kobana.com.br/v1/invoices \
-H "Authorization: Bearer $KOBANA_TOKEN" \
-H "X-Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"billing_account_id": "8f3b2c1a-5d4e-4f6a-9b7c-2e1d0a9f8b7c",
"due_date": "2026-06-30",
"collection_method": "manual_charge",
"line_items": [
{
"description": "On-demand consulting — June/2026",
"quantity": 8,
"unit_amount": 250.0,
"service_item_id": "7c8d9e0f-1a2b-4c3d-9e4f-5a6b7c8d9e0f"
}
]
}'response
{
"data": {
"id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"number": "INV-001234",
"status": "draft",
"subtotal": 2000.0,
"tax": 0,
"total": 2000.0,
"due_date": "2026-06-30"
}
}