Overview

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.

How It Works

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.

API Endpoints

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

Important Behaviors

Soft delete: Invoices are soft-deleted, not permanently removed.
Currency normalization: The currency field is automatically lowercased before storage.
Metadata merge: On update, metadata is merged with existing values, not replaced.
Update scope: Only metadata and purchase_order are editable via update — other fields are immutable after creation.
Void restrictions: Cannot void advance invoices or invoices with partial payments.
Uncollectible restrictions: Only open or past_due invoices can be marked uncollectible. Advance invoices and those with partial payments are excluded.
Customer address default: If customer_address is not provided on create, it auto-populates from the customer's default billing address.
Period end default: If period_end is not provided, it defaults to period_start.
Expandable relationships: subscription, charge, user, discount can be expanded via the expand query parameter.

Invoice Statuses

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

Billing Methods

Method	Description
`charge_automatically`	System attempts to charge the customer's default payment method
`send_invoice`	Customer receives an invoice to pay manually

Invoice Object

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