Invoice Schema
Billing documents with line items, payment terms, and automatic calculations
The Invoice schema defines the structure and properties of invoice objects in the Payload API. Invoices represent billing documents sent from billers to payers, containing comprehensive line items, payment terms, contact information, and automatic total calculations for professional billing workflows.
Invoice Object Properties
Complete reference for all properties available in the Invoice schema
attachmentsInvoiceAttachmentarray
Collection of all file attachments associated with this invoice. May include PDFs, images, receipts, or other supporting documentation. Expanded by default to show all attached files.
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
autopay_settingsobject
Configuration for automatic payment behavior on this invoice. Controls whether the invoice can automatically charge the payer's default payment method (if configured) when due, or if manual payment is required. Essential for managing recurring payments and subscription billing.
allowedboolean
Controls whether automatic payment is allowed for this invoice. When set to true, if the payer has an automatic payment method configured, the invoice will be automatically charged when due. When false, the invoice must be paid manually.
billerobject
Information about the merchant or service provider who issued this invoice. Includes the biller account and optionally the specific payment method for receiving funds. The biller receives payment when the payer pays this invoice.
accountAccountobject
The expanded biller account object. When included, this provides full account details for the merchant or service provider who issued this invoice and will receive payment.
Visibility: explicit
account_id ID of Accountstring
The unique identifier of the processing account that issued this invoice and will receive payment. This is the merchant or service provider being paid. If not specified, the system will attempt to select an applicable biller account automatically. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$Required if:
biller[account]=nullmethodPaymentMethodobject
The expanded payment method object for funding. When included, this shows where the funds from this invoice payment will be deposited (the merchant's bank account or payment destination).
Visibility: explicit
method_id ID of PaymentMethodstring
The unique identifier of the payment method where funds from this invoice will be deposited. If specified, payments for this invoice will be sent to this payment method. If not set, the biller account's default funding method will be used. Must belong to the biller account. (ID prefix: pm)
Pattern:
^pm_[A-Za-z0-9]+$billing_schedule_id ID of BillingSchedulestring
The unique identifier of the billing schedule that generated this invoice. If present, this invoice was automatically created as part of a recurring billing schedule. If null, this is a standalone, one-time invoice not associated with any recurring billing. Use this to track which subscription or recurring billing arrangement generated this invoice. (ID prefix: bscd)
Pattern:
^bscd_[A-Za-z0-9]+$created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
default_tax_ratenumber (double)
The default tax rate (as a percentage) applied to taxable line items on this invoice. For example, 8.5 represents an 8.5% tax rate. This rate is applied automatically to line items unless overridden at the item level. Used for calculating the tax portion of the invoice total.
descriptionstring
Text description providing context about this invoice. Typically includes what the invoice is for, such as "Monthly subscription - January 2024" or "Consulting services". This appears on the invoice and helps both payer and biller understand what is being charged.
Max length: 512
due_datestring (date)Required
The date by which payment is due for this invoice. If autopay is enabled, the invoice will be automatically charged on this date. For manual payments, this serves as the payment deadline. Late fees or payment reminders may be triggered based on this date. Required for all invoices.
external_uidstring
Optional unique external identifier for this invoice from an external system. Maximum length of 64 characters. When provided, this can be used to look up the invoice or perform upsert operations (update if exists, create if not). Useful for maintaining consistency with external accounting, ERP, or billing systems. Prevents duplicate invoice creation when syncing from external sources.
Max length: 64
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: inv)
Pattern:
^inv_[A-Za-z0-9]+$itemsInvoiceItemarray
Collection of all top-level line items on this invoice. Expanded by default to show all invoice charges, products, and services.
modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
numberstring
A unique, human-readable invoice number for reference and organization. Automatically generated in the format "INV-000001" if not provided, incrementing for each new invoice within the same organization. Can be customized if you want to use your own numbering scheme. Used for tracking, customer communication, and accounting records.
Max length: 32
objectenum[string]Read-only
String representing the object type for this resource.
Values:
invoicepaid_timestampstring (date)Read-only
The date and time when this invoice was fully paid (when balance_due reached zero). Read-only field that is automatically set when the invoice transitions to "paid" status. Useful for tracking payment completion, calculating payment cycles, and reporting on collection times. Null until the invoice is fully paid.
payerobject
Information about the customer being invoiced. Includes the payer account and optionally the specific payment method to use for autopay. The payer is responsible for paying this invoice and will receive communications about it.
accountAccountobject
The expanded payer account object. When included, this provides full account details for who is being invoiced and is responsible for payment.
Visibility: explicit
account_id ID of Accountstring
The unique identifier of the account being invoiced. This is the payer who owes payment and will receive the invoice. Required if payer account is not provided inline. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$Required if:
payer[account]=nullmethodPaymentMethodobject
The expanded payment method object for autopay. When included, this shows the specific payment method (card, bank account, etc.) that will be automatically charged if autopay is enabled for this invoice.
Visibility: explicit
method_id ID of PaymentMethodstring
The unique identifier of the payment method to use for automatic payment of this invoice. If specified and autopay is enabled, this payment method will be charged when the invoice is due. If not set, the payer account's default payment method will be used. Not required to belong to the payer account. (ID prefix: pm)
Pattern:
^pm_[A-Za-z0-9]+$payment_linksPaymentLinkarray
List of payment links associated with this invoice. Payment links provide secure URLs that can be sent to customers for easy online payment. These links can be emailed automatically when an invoice is published or created manually. Use this to access all payment links generated for collecting payment on this invoice.
paymentsPaymentAllocationarray
Collection of all payment allocations applied to this invoice. Each allocation represents a payment (or portion of a payment) that reduces the invoice balance. Expanded by default to show complete payment history for the invoice.
statusenum[string]
The current status of this invoice. Possible values: "draft" (not yet published/sent), "open" (published and awaiting payment, same as unpaid), "unpaid" (published with no payments), "partially_paid" (some payment received but balance remains), "paid" (fully paid), or "closed" (manually closed/cancelled). Status transitions are restricted - for example, paid invoices cannot be modified.
Values:
draft, open, unpaid, partially_paid, paid, closed, synctotalsobject
Financial summary of this invoice, including subtotal, tax, total amounts, and payment status. All fields are read-only and automatically calculated based on the line items and payments associated with this invoice. Provides a quick overview of the invoice's financial state.
balance_duenumber (double)Read-only
The remaining unpaid balance on this invoice (total - paid). Read-only field that represents the outstanding amount the payer still owes. When this reaches zero, the invoice is fully paid.
paidnumber (double)Read-only
The total amount that has been successfully paid toward this invoice. Read-only field that updates as payments are received and allocated to this invoice. Use this to track how much has been collected.
subtotalnumber (double)Read-only
The subtotal of all line items on this invoice before tax is applied. This is the sum of all line item amounts (value * qty for each item). Read-only field that is automatically calculated based on the invoice items. Represents the pre-tax total.
taxnumber (double)Read-only
The total tax amount for this invoice. Calculated by applying tax rates to taxable line items. Read-only field that updates when line items or tax rates change. This amount is added to the subtotal to get the total amount due.
totalnumber (double)Read-only
The total amount due for this invoice (subtotal + tax). This is the full amount the payer owes. Read-only field that is automatically calculated from line items and tax. Represents the complete invoice amount before any payments are applied.
typestring
Arbitrary classification or category for this invoice. Use this to organize invoices by type, such as "subscription", "one-time", "service", "product", or custom categories specific to your business needs. Helpful for filtering, reporting, and organization.
Max length: 24