Invoices represent billing documents sent to customers. They can be generated automatically from subscriptions or created manually for one-time charges. Each invoice tracks amounts due, payments received, and billing status.
- Invoice creation - Invoices are created automatically when subscriptions renew or manually via the API
- Payment collection - Invoices can be paid automatically or manually marked as paid
- Status tracking - Track invoice lifecycle from draft to paid, void, or uncollectible
Example: When a subscription renews, the system automatically creates an invoice with the plan amount, applies any discounts, calculates taxes, and attempts to collect payment from the customer's default payment method.
| Method | Endpoint | Description |
|---|
GET | /api/v1/core/invoices | List all invoices |
POST | /api/v1/core/invoices | Create an invoice |
GET | /api/v1/core/invoices/{id} | Get an invoice |
PUT | /api/v1/core/invoices/{id} | Update an invoice |
POST | /api/v1/core/invoices/{id}/pay_offline | Record an offline payment |
POST | /api/v1/core/invoices/{id}/void | Void an invoice |
POST | /api/v1/core/invoices/{id}/uncollectible | Mark as uncollectible |
| Status | Description |
|---|
draft | Invoice is being prepared, not yet finalized |
open | Invoice is finalized and awaiting payment |
paid | Payment has been collected successfully |
past_due | Payment deadline has passed |
void | Invoice has been canceled |
uncollectible | Invoice has been marked as uncollectible |
| Method | Description |
|---|
charge_automatically | System attempts to charge the customer's default payment method |
send_invoice | Customer receives an invoice to pay manually |
| Attribute | Type | Description |
|---|
id | integer | Unique identifier for the invoice |
user_id | integer | ID of the customer (expandable) |
subscription_id | integer | ID of the associated subscription (expandable) |
charge_id | integer | ID of the successful charge (expandable) |
discount_id | integer | ID of the applied discount (expandable) |
number | string | Invoice number |
status | string | Invoice status (see statuses above) |
currency | string | Three-letter ISO currency code |
amount_due | integer | Amount due in cents |
amount_paid | integer | Amount paid in cents |
amount_remaining | integer | Remaining amount in cents |
subtotal | integer | Subtotal before tax in cents |
tax | integer | Tax amount in cents |
total | integer | Total amount in cents |
paid | boolean | Whether the invoice has been paid |
billing | string | Billing method |
billing_reason | string | Reason for the invoice |
auto_advance | boolean | Whether invoice auto-finalizes |
due_date | timestamp | Unix timestamp when payment is due |
period_start | timestamp | Unix timestamp of billing period start |
period_end | timestamp | Unix timestamp of billing period end |
starting_balance | integer | Customer balance before invoice |
ending_balance | integer | Customer balance after invoice |
plan_name | string | Name of the associated plan |
product_name | string | Name of the associated product |
customer_address | object | Customer's billing address |
hosted_invoice_url | string | URL to hosted invoice page |
invoice_pdf | string | URL to download invoice PDF |
payment_link | string | URL for customer to pay |
post_payment_credit_notes_amount | integer | Credit notes after payment |
pre_payment_credit_notes_amount | integer | Credit notes before payment |
is_imported | boolean | Whether invoice was imported |
notes | string | Invoice footer/notes |
metadata | object | Key-value pairs for storing additional data |
finalized_at | timestamp | Unix timestamp when finalized |
paid_at | timestamp | Unix timestamp when paid |
voided_at | timestamp | Unix timestamp when voided |
marked_uncollectible_at | timestamp | Unix timestamp when marked uncollectible |
created_at | timestamp | Unix timestamp of creation |
updated_at | timestamp | Unix timestamp of last update |
deleted_at | timestamp | Unix timestamp of deletion |
