Invoices

Get invoice preview

Use when showing a customer what they will be charged (e.g. preview before checkout or plan change). No invoice is created.

post/invoices/preview

Request body

hide_zero_charges_line_itemsboolean

hide_zero_charges_line_items indicates whether to hide line items with zero cost

period_endstring date-time

period_end is the optional end date of the period to preview

period_startstring date-time

period_start is the optional start date of the period to preview

subscription_idstring required

subscription_id is the unique identifier of the subscription to preview invoice for

Response

adjustment_amountstring

adjustment_amount is the total sum of credit notes of type "adjustment". These are non-cash reductions applied to the invoice (e.g. goodwill credit, billing correction).

amount_duestring

amount_due is the total amount that needs to be paid for this invoice

amount_paidstring

amount_paid is the amount that has already been paid towards this invoice

amount_remainingstring

amount_remaining is the outstanding amount still owed on this invoice (calculated as amount_due minus amount_paid)

billing_periodstring

billing_period describes the billing period this invoice covers (e.g., "January 2024", "Q1 2024")

billing_reasonstring

billing_reason indicates why this invoice was generated (e.g., "subscription_billing", "manual_charge")

billing_sequenceinteger

billing_sequence is the sequential number indicating the billing cycle for subscription invoices

created_atstring date-time

created_bystring

currencystring

currency is the three-letter ISO currency code (e.g., USD, EUR, GBP) that applies to all monetary amounts on this invoice

customer_idstring

customer_id is the ID of the customer who will receive this invoice

descriptionstring

description is an optional description or notes about this invoice

due_datestring date-time

due_date is the date when payment for this invoice is due

environment_idstring

environment_id is the ID of the environment this invoice belongs to (for multi-environment setups)

finalized_atstring date-time

finalized_at is the timestamp when this invoice was finalized and made ready for payment

idstring

id is the unique identifier for this invoice

idempotency_keystring

idempotency_key is a unique key used to prevent duplicate invoice creation when retrying API calls

invoice_numberstring

invoice_number is the human-readable invoice number displayed to customers (e.g., INV-2024-001)

invoice_pdf_urlstring

invoice_pdf_url is the URL where customers can download the PDF version of this invoice

invoice_status'DRAFT' | 'FINALIZED' | 'VOIDED' | 'SKIPPED'

invoice_type'SUBSCRIPTION' | 'ONE_OFF' | 'CREDIT'

issue_datestring date-time

issue_date is the user-facing date of the invoice. Defaults to created_at if not set.

last_computed_atstring date-time

last_computed_at is the timestamp when this invoice was last computed by ComputeInvoice

metadataTypesMetadata

overpaid_amountstring

overpaid_amount is the amount overpaid if payment_status is OVERPAID (amount_paid - total)

paid_atstring date-time

paid_at is the timestamp when this invoice was fully paid

period_endstring date-time

period_end is the end date of the billing period covered by this invoice

period_startstring date-time

period_start is the start date of the billing period covered by this invoice

recalculated_invoice_idstring

recalculated_invoice_id is the ID of the replacement invoice created when this invoice was voided and recalculated. When set, it forms a parent→child link from this (voided) invoice to the new replacement invoice.

refunded_amountstring

refunded_amount is the total sum of credit notes of type "refund". These are actual refunds issued to the customer.

status'published' | 'deleted' | 'archived'

subscription_customer_idstring

subscription_customer_id is the subscription owner's customer ID (Subscription.CustomerID). It may differ from customer_id when the subscription uses an invoicing customer. Set internally; nullable in DB.

subscription_idstring

subscription_id is the ID of the subscription this invoice is associated with (only present for subscription-based invoices)

subtotalstring

subtotal is the sum of all line items before any taxes, discounts, or additional fees

tenant_idstring

totalstring

total is the final amount including taxes, fees, and discounts

total_discountstring

total_discount is the sum of all coupon discounts applied to the invoice

total_prepaid_credits_appliedstring

total_prepaid_credits_applied is the total amount of prepaid credits applied to this invoice.

total_taxstring

total_tax is the sum of all taxes combined at the invoice level.

updated_atstring date-time

updated_bystring

versioninteger

version is the version number for tracking changes to this invoice

voided_atstring date-time

voided_at is the timestamp when this invoice was voided or cancelled

Changes

Changed in 7 of the 12 revisions of this API.32634

Jun 29, 2026cef2964c102c212See the full diff
- ●
  removed the optional property subscription/customer_timezone from the response with the 200 status
  response-optional-property-removed
- ●
  added the new VOIDED enum value to the payment_status response property for the response status 200
  response-property-enum-value-added
- ○
  added the optional property customer/integrations/items/metadata to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property customer/timezone to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property line_items/items/adjusted_entitlement_quantity to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property line_items/items/subscription_line_item_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/coupon_associations/items/coupon/coupon_code to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/coupon_associations/items/subscription_line_item to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/customer/integrations/items/metadata to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/customer/timezone to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/line_items/items/commitment_time_buckets to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/line_items/items/price/sequence to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/synced_price_sequence to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/timezone to the response with the 200 status
  response-optional-property-added
May 18, 2026f62d8a5fe7cf41See the full diff
- ●
  removed the optional property details from the response with the 400 status
  response-optional-property-removed
- ●
  removed the optional property details from the response with the 500 status
  response-optional-property-removed
- ●
  added the new too_many_requests enum value to the code response property for the response status 400
  response-property-enum-value-added
- ●
  added the new too_many_requests enum value to the code response property for the response status 500
  response-property-enum-value-added
- ○
  added the optional property issue_date to the response with the 200 status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 18, 20260cb3425d658095See the full diff
- ●
  removed the optional property subscription/line_items/items/trial_period_days from the response with the 200 status
  response-optional-property-removed
- ●
  added the new ONETIME enum value to the line_items/items/commitment_info/duration response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the subscription/billing_period response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the subscription/commitment_duration response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the subscription/line_items/items/billing_period response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the subscription/line_items/items/commitment_duration response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ONETIME enum value to the subscription/line_items/items/price/billing_period response property for the response status 200
  response-property-enum-value-added
- ●
  added the new delegated_invoicing enum value to the subscription/subscription_type response property for the response status 200
  response-property-enum-value-added
- ●
  added the new grouped_invoicing enum value to the subscription/subscription_type response property for the response status 200
  response-property-enum-value-added
- ○
  added the optional property subscription/auto_invoice_threshold to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/line_items/items/addon_association_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription_customer_id to the response with the 200 status
  response-optional-property-added
- ○
  removed the ONETIME enum value from the subscription/billing_cadence response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the ONETIME enum value from the subscription/line_items/items/price/billing_cadence response property for the response status 200
  response-property-enum-value-removed
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 23, 202682f205e0f42922See the full diff
- ●
  removed the optional property subscription/line_items/items/price/trial_period from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property subscription/line_items/items/trial_period from the response with the 200 status
  response-optional-property-removed
- ○
  added the optional property subscription/line_items/items/price/trial_period_days to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/line_items/items/trial_period_days to the response with the 200 status
  response-optional-property-added
Apr 6, 20264ded3711f401189See the full diff
- ▲
  the billing_period response's property type/format changed from string/date-time to string/ for status 200
  response-property-type-changed
- ●
  removed the optional property customer/parent_customer from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property customer/parent_customer_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property error from the response with the 400 status
  response-optional-property-removed
- ●
  removed the optional property error from the response with the 500 status
  response-optional-property-removed
- ●
  removed the optional property subscription/customer/parent_customer from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property subscription/customer/parent_customer_id from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property success from the response with the 400 status
  response-optional-property-removed
- ●
  removed the optional property success from the response with the 500 status
  response-optional-property-removed
- ○
  added the optional property code to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property code to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property http_status_code to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property http_status_code to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property message to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property message to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property subscription/subscription_type to the response with the 200 status
  response-optional-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 4, 2026d1860fe0ee67213See the full diff
- ▲
  the period_end request property type/format changed from string/ to string/date-time
  request-property-type-changed
- ▲
  the period_start request property type/format changed from string/ to string/date-time
  request-property-type-changed
- ●
  added the new SKIPPED enum value to the invoice_status response property for the response status 200
  response-property-enum-value-added
- ○
  added the optional property customer/integrations to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property last_computed_at to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property subscription/customer/integrations to the response with the 200 status
  response-optional-property-added
This revision also has 223 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Mar 20, 2026bc91c95fbb1a2See the full diff
- ○
  added the new optional request property hide_zero_charges_line_items
  new-optional-request-property
- ○
  added the optional property recalculated_invoice_id to the response with the 200 status
  response-optional-property-added
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history