Skip to main content

​
Overview

BoxBilling automatically generates invoices based on subscription billing periods. The invoice generation pipeline handles charge calculation, tax application, coupon discounts, wallet credit consumption, and progressive billing credits.

​
Invoice lifecycle

  DRAFT → FINALIZED → PAID
                   ↘ VOIDED
StatusDescription
DraftEditable, not yet issued
FinalizedIssued to customer, due for payment
PaidFully settled
VoidedCanceled after finalization

​
Invoice types

TypeDescription
subscriptionRegular periodic billing
add_onOne-time add-on charge
creditCredit adjustment
one_offManual one-time charge
progressive_billingMid-period usage threshold billing

​
Invoice generation pipeline

When an invoice is generated for a subscription billing period, the system executes these steps:

​
1. Calculate charge fees

For each charge on the subscription’s plan:
  • Aggregate usage via the appropriate billable metric
  • Apply the charge model calculator (standard, graduated, volume, etc.)
  • Apply min/max price capping if configured
  • Handle charge filters for segmented pricing

​
2. Generate commitment true-up fees

If the plan has minimum commitments and actual charges are below the minimum, a true-up fee is added for the difference.

​
3. Apply taxes

Taxes are resolved hierarchically:
  1. Charge-level taxes (most specific)
  2. Plan-level taxes
  3. Customer-level taxes
  4. Organization-level defaults
Each fee gets individual AppliedTax records. Fee-level taxes are aggregated into the invoice tax_amount.

​
4. Apply coupon discounts

Active coupons on the customer are applied:
  • Fixed amount — deducted directly, capped at remaining subtotal
  • Percentage — calculated as subtotal × rate / 100
Coupons are consumed based on their frequency:
  • once — terminated after single use
  • recurring — decremented per billing period
  • forever — never consumed

​
5. Apply wallet credits

If the customer has active wallets, credits are consumed in priority order (lower priority number = consumed first). Wallet transactions and invoice settlements are recorded.

​
6. Subtract progressive billing credits

If progressive billing invoices were issued during the period, their total is credited on the final period invoice to prevent double-billing.

​
Automatic invoice generation

The generate_periodic_invoices task runs hourly and creates invoices for:
  • Active subscriptions whose billing period has ended (pay-in-arrear)
  • Active subscriptions whose billing period is starting (pay-in-advance)

​
Manual operations

​
Finalize an invoice

POST /v1/invoices/{id}/finalize
Moves the invoice from draft to finalized. Applies wallet credits and sends an invoice.finalized webhook.

​
Mark as paid

POST /v1/invoices/{id}/pay
Marks the invoice as paid. Sends an invoice.paid webhook.

​
Void an invoice

POST /v1/invoices/{id}/void
Voids a finalized invoice. Sends an invoice.voided webhook.

​
Delete a draft

DELETE /v1/invoices/{id}
Only draft invoices can be deleted.

​
Fees

Fees are the individual line items on an invoice. Each fee represents a calculated charge:
Fee typeDescription
chargeUsage-based charge from a billable metric
subscriptionBase plan subscription fee
add_onOne-time add-on charge
creditCredit adjustment
commitmentMinimum commitment true-up

​
Fee properties

Each fee records:
  • amount_cents — pre-tax amount
  • taxes_amount_cents — tax amount
  • total_amount_cents — amount + taxes
  • units — usage units consumed
  • events_count — number of events
  • unit_amount_cents — price per unit

​
Invoice settlements

Invoices can be settled through multiple sources:
Settlement typeDescription
paymentDirect payment (Stripe, Adyen, etc.)
credit_noteApplied credit from a credit note
wallet_creditPrepaid wallet credits
An invoice is automatically marked as paid when settlements equal or exceed the total.

​
Credit notes

Credit notes are issued against finalized invoices for adjustments, refunds, or corrections.

​
Create a credit note

curl -X POST /v1/credit_notes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "invoice-uuid",
    "customer_id": "customer-uuid",
    "credit_note_type": "credit",
    "reason": "order_change",
    "items": [
      {
        "fee_id": "fee-uuid",
        "amount_cents": 500
      }
    ]
  }'

​
Credit note workflow

  1. Create (draft) → Finalize → Apply to invoice or Void
  2. Credit notes have a balance_amount_cents that decreases as credits are applied
  3. Applying credit to an invoice creates an InvoiceSettlement record

​
Webhooks

EventTrigger
invoice.createdInvoice generated
invoice.finalizedInvoice finalized
invoice.paidInvoice fully paid
invoice.voidedInvoice voided

​
API endpoints

MethodPathDescription
GET/v1/invoicesList invoices
GET/v1/invoices/{id}Get invoice details
PUT/v1/invoices/{id}Update a draft invoice
POST/v1/invoices/{id}/finalizeFinalize an invoice
POST/v1/invoices/{id}/payMark as paid
POST/v1/invoices/{id}/voidVoid an invoice
GET/v1/invoices/{id}/settlementsList settlements
DELETE/v1/invoices/{id}Delete a draft invoice
GET/v1/feesList fees
GET/v1/fees/{id}Get fee details
GET/v1/credit_notesList credit notes
POST/v1/credit_notesCreate a credit note
POST/v1/credit_notes/{id}/finalizeFinalize a credit note
POST/v1/credit_notes/{id}/voidVoid a credit note