Invoicing

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

Status	Description
draft	Editable, not yet issued
finalized	Issued to customer, due for payment
paid	Fully settled
voided	Canceled after finalization

Invoice types

Type	Description
subscription	Regular periodic billing
add_on	One-time add-on charge
credit	Credit adjustment
one_off	Manual one-time charge
progressive_billing	Mid-period usage threshold billing

Invoice properties

Each invoice contains the following financial fields:

Field	Description
subtotal_cents	Pre-tax amount
tax_amount_cents	Total tax
total_cents	Final amount including tax
prepaid_credit_amount_cents	Wallet credits applied
coupons_amount_cents	Coupon discounts applied
progressive_billing_credit_amount_cents	Progressive billing credits applied
currency	Invoice currency (default: USD)
billing_period_start	Start of the billing period
billing_period_end	End of the billing period
due_date	Payment due date
issued_at	When the invoice was issued
paid_at	When the invoice was paid

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_cents.

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)

One-off invoices

Create invoices with custom line items that are not tied to a subscription:

POST /v1/invoices/one_off

{
  "customer_id": "customer-uuid",
  "currency": "USD",
  "line_items": [
    {
      "description": "Consulting hours",
      "quantity": 10,
      "unit_price": 15000,
      "charge_id": null,
      "metric_code": null
    }
  ],
  "due_date": "2026-04-01T00:00:00Z",
  "billing_entity_id": "entity-uuid"
}

Each line item includes:

Field	Description
description	Line item description
quantity	Number of units
unit_price	Price per unit
amount	Total amount (alternative to quantity × unit_price)
charge_id	Optional reference to a charge
metric_code	Optional billable metric code

Invoice preview

Preview an invoice for a subscription without persisting anything:

POST /v1/invoices/preview

{
  "subscription_id": "subscription-uuid",
  "billing_period_start": "2026-03-01T00:00:00Z",
  "billing_period_end": "2026-04-01T00:00:00Z"
}

Only subscription_id is required — billing period boundaries are optional and default to the subscription’s current period.

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.

Update a draft invoice

PUT /v1/invoices/{id}

Updatable fields: status, due_date, issued_at, paid_at.

Send invoice email

POST /v1/invoices/{id}/send_email

Sends the invoice to the customer via email.

Send payment reminder

POST /v1/invoices/{id}/send_reminder

Sends a payment reminder for an overdue invoice.

Download or preview PDF

POST /v1/invoices/{id}/download_pdf    # Download PDF
GET  /v1/invoices/{id}/pdf_preview     # Inline PDF preview

Bulk operations

Bulk finalize

POST /v1/invoices/bulk_finalize

Finalize multiple draft invoices in one request.

Bulk void

POST /v1/invoices/bulk_void

Void multiple invoices in one request.

Fees

Fees are the individual line items on an invoice. Each fee represents a calculated charge:

Fee type	Description
charge	Usage-based charge from a billable metric
subscription	Base plan subscription fee
add_on	One-time add-on charge
credit	Credit adjustment
commitment	Minimum commitment true-up

Fee properties

Each fee records:

Field	Description
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
payment_status	pending, succeeded, failed, refunded
description	Fee description
metric_code	Associated billable metric code
properties	Additional fee properties (JSON)

Fee payment status

Each fee tracks its own payment status independently:

Status	Description
pending	Payment not yet processed
succeeded	Successfully paid
failed	Payment failed
refunded	Payment was refunded

Update a fee

PUT /v1/fees/{id}

Updatable fields: payment_status, description, taxes_amount_cents.

Estimate fees

POST /v1/events/estimate_fees

Estimate fees for a hypothetical event without persisting anything.

Invoice settlements

Invoices can be settled through multiple sources:

Settlement type	Description
payment	Direct payment (Stripe, Adyen, etc.)
credit_note	Applied credit from a credit note
wallet_credit	Prepaid wallet credits

Each settlement records: invoice_id, settlement_type, source_id (polymorphic reference), and amount_cents.

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.

Credit note types

Type	Description
credit	Credit applied to future invoices
refund	Refund to original payment method
offset	Offset against the invoice balance

Credit note statuses

Field	Values	Description
status	draft, finalized	Overall credit note status
credit_status	available, consumed, voided	Credit availability
refund_status	pending, succeeded, failed	Refund processing state

Credit note reasons

Reason	Description
duplicated_charge	Duplicate billing
product_unsatisfactory	Product quality issue
order_change	Order modification
order_cancellation	Order canceled
fraudulent_charge	Fraudulent activity
other	Other reason

Create a credit note

POST /v1/credit_notes

{
  "invoice_id": "invoice-uuid",
  "customer_id": "customer-uuid",
  "credit_note_type": "credit",
  "reason": "order_change",
  "description": "Adjustment for plan change",
  "credit_amount_cents": 500,
  "refund_amount_cents": 0,
  "items": [
    {
      "fee_id": "fee-uuid",
      "amount_cents": 500
    }
  ]
}

Credit note financial fields

Field	Description
credit_amount_cents	Available credit amount
refund_amount_cents	Refund amount
balance_amount_cents	Remaining unused credit
total_amount_cents	Total credit note amount
taxes_amount_cents	Tax amount
currency	Credit note currency

Credit note operations

Operation	Endpoint	Description
Update	PUT /v1/credit_notes/{id}	Update description, credit/refund amounts
Finalize	POST /v1/credit_notes/{id}/finalize	Finalize a draft credit note
Void	POST /v1/credit_notes/{id}/void	Void a credit note
Send email	POST /v1/credit_notes/{id}/send_email	Email credit note to customer
Download PDF	POST /v1/credit_notes/{id}/download_pdf	Download credit note as PDF

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

Event	Trigger
invoice.created	Invoice generated
invoice.finalized	Invoice finalized
invoice.paid	Invoice fully paid
invoice.voided	Invoice voided

API endpoints

Invoices

Method	Path	Description
GET	/v1/invoices	List invoices
GET	/v1/invoices/{id}	Get invoice details
PUT	/v1/invoices/{id}	Update a draft invoice
DELETE	/v1/invoices/{id}	Delete a draft invoice
POST	/v1/invoices/{id}/finalize	Finalize an invoice
POST	/v1/invoices/{id}/pay	Mark as paid
POST	/v1/invoices/{id}/void	Void an invoice
POST	/v1/invoices/{id}/send_email	Send invoice email
POST	/v1/invoices/{id}/send_reminder	Send payment reminder
POST	/v1/invoices/{id}/download_pdf	Download invoice PDF
GET	/v1/invoices/{id}/pdf_preview	Preview invoice PDF inline
GET	/v1/invoices/{id}/settlements	List settlements
POST	/v1/invoices/one_off	Create a one-off invoice
POST	/v1/invoices/preview	Preview invoice
POST	/v1/invoices/bulk_finalize	Bulk finalize drafts
POST	/v1/invoices/bulk_void	Bulk void invoices

Fees

Method	Path	Description
GET	/v1/fees	List fees
GET	/v1/fees/{id}	Get fee details
PUT	/v1/fees/{id}	Update a fee

Credit notes

Method	Path	Description
GET	/v1/credit_notes	List credit notes
GET	/v1/credit_notes/{id}	Get credit note
POST	/v1/credit_notes	Create a credit note
PUT	/v1/credit_notes/{id}	Update a credit note
POST	/v1/credit_notes/{id}/finalize	Finalize a credit note
POST	/v1/credit_notes/{id}/void	Void a credit note
POST	/v1/credit_notes/{id}/send_email	Send credit note email
POST	/v1/credit_notes/{id}/download_pdf	Download credit note PDF