Billing & invoicing

How FlexPrice generates invoices and processes payments

FlexPrice automatically generates invoices based on subscriptions, usage, and one-time charges, then processes payments through integrated payment providers.

Invoice Lifecycle

1. Draft

   Invoice is created with line items but not yet finalized

2. Open

   Invoice is finalized and sent to customer for payment

3. Paid

   Payment received and applied to invoice

4. Void

   Invoice cancelled and marked as invalid

Invoice Structure

An invoice contains:

{
  "id": "inv_uuid",
  "customer_id": "cust_uuid",
  "status": "OPEN",
  "invoice_type": "SUBSCRIPTION",
  "subtotal": 10000,
  "tax": 800,
  "total": 10800,
  "amount_due": 8800,
  "currency": "USD",
  "billing_period_start": "2024-03-01T00:00:00Z",
  "billing_period_end": "2024-03-31T23:59:59Z",
  "line_items": [
    {
      "description": "Professional Plan",
      "quantity": 1,
      "unit_amount": 9900,
      "amount": 9900
    },
    {
      "description": "API Calls (15,234 calls)",
      "quantity": 15234,
      "unit_amount": 10,
      "amount": 15234
    }
  ],
  "discounts": [
    {
      "amount": 2000,
      "description": "Early bird discount"
    }
  ],
  "credit_applied": 2000
}

All amounts are in the smallest currency unit (cents for USD).

Invoice Types

Subscription

Generated automatically at billing cycle:

• Base subscription fee
• Usage charges for the period
• Add-on charges
• Prorated amounts for changes

Created at the end of each billing period.

One-Time

Manual invoice for custom charges:

{
  "invoice_type": "ONE_TIME",
  "line_items": [
    {
      "description": "Professional Services",
      "amount": 500000
    }
  ]
}

Used for implementation fees, custom work, etc.

Usage

Pure usage invoice without subscription:

{
  "invoice_type": "USAGE",
  "line_items": [
    {
      "description": "API Calls",
      "quantity": 50000,
      "unit_amount": 10
    }
  ]
}

For pay-as-you-go customers.

Line Items

Each line item represents a charge:

• Subscription fees - Fixed recurring charges
• Usage charges - Metered usage from meters
• Add-ons - Optional purchased add-ons
• Overage - Usage beyond included amounts
• Proration - Partial period charges

Line items include detailed usage breakdown when grouped by dimensions (endpoint, region, etc.).

Amount Calculation

Subtotal = Sum of all line items
- Discounts (coupons, promotions)
= Subtotal after discounts
+ Taxes (based on customer location)
= Total
- Credits applied (from wallet)
= Amount Due

Credits are applied after discounts and taxes, maximizing customer benefit.

Billing Cycles

Invoices are generated based on subscription billing cadence:

• Monthly - Invoice at end of each month
• Quarterly - Invoice every 3 months
• Annual - Invoice once per year
• Custom - Define your own billing period

Anniversary vs Calendar

Anniversary

Bill based on subscription start date:

• Started March 15 → Bill on 15th of each month
• Consistent with customer’s signup date
• Proration on first invoice if mid-month

Calendar

Bill at end of calendar month:

• All customers billed on same day
• Easier batch processing
• First invoice always prorated

Payment Processing

Once invoice is finalized:

1. Invoice finalized

   Invoice status changes from DRAFT to OPEN

2. Payment attempted

   Charge customer via configured payment method

3. Payment recorded

   Successful payment updates invoice to PAID status

4. Receipt sent

   Customer receives payment confirmation

Failed payments trigger retry logic and can result in subscription suspension.

Integration with Payment Providers

FlexPrice syncs invoices with:

• Stripe - Create/update Stripe invoices
• Chargebee - Sync to Chargebee subscription
• Razorpay - Generate payment links
• Custom - Webhook events for custom systems

{
  "integration_entity_mapping": {
    "provider": "stripe",
    "external_id": "in_1234567890"
  }
}

External invoice IDs are stored for reconciliation and two-way sync.

Credit Notes

Issue refunds or adjustments:

{
  "invoice_id": "inv_uuid",
  "amount": 5000,
  "type": "REFUND",
  "reason": "Billing error"
}

Credit notes reduce the invoice amount and can trigger payment refunds.

Proration

When subscriptions change mid-period:

1. Calculate unused time on old plan
2. Calculate used time on new plan
3. Credit for unused portion
4. Charge for new portion
5. Net amount added to next invoice

Proration ensures fair billing when customers upgrade, downgrade, or cancel.

Related Resources

Subscriptions

Subscription lifecycle and billing

Invoices Guide

Detailed invoice management

List Invoices API

API reference for invoices

Payments

Payment processing and methods