The Invoice object
Invoices are statements of amounts owed by a customer. They are generated one-off, or periodically from a subscription. They contain invoice items and proration adjustments that may be caused by subscription upgrades or downgrades. Invoices settle in USDC on Solana. If your invoice is configured for automatic collection, Zoneless finalizes the invoice and attempts payment after webhooks are delivered. If configured for send_invoice, Zoneless emails the customer with a link to the hosted invoice page. Any customer credit balance is applied before determining the amount due.
Attributes
id string Unique identifier for the object. Zoneless invoice IDs are prefixed with in_z_.
object string String representing the object’s type. Objects of the same type share the same value.
account_countrynullable string The country of the business associated with this invoice, most often the business creating the invoice.
account_namenullable string The public name of the business associated with this invoice, most often the business creating the invoice.
amount_due integer Final amount due at this time for this invoice. If the invoice’s total is smaller than the minimum charge amount, or if there is account credit that can be applied, amount_due may be 0. The payment collected for the invoice is for this amount. For USDC, this is cents (e.g., 100 = $1 USDC).
amount_overpaid integer Amount that was overpaid on the invoice. The amount overpaid is credited to the customer’s credit balance.
amount_paid integer The amount, in the smallest currency unit, that was paid.
amount_remaining integer The difference between amount_due and amount_paid, in the smallest currency unit.
attempt_count integer Number of payment attempts made for this invoice, from the perspective of the payment retry schedule. Any payment attempt counts as the first attempt, and subsequently only automatic retries increment the attempt count.
attempted boolean Whether an attempt has been made to pay the invoice. An invoice is not attempted until after the invoice.created webhook is delivered, so you might not want to display that invoice as unpaid to your users yet.
auto_advance boolean Controls whether Zoneless performs automatic collection of the invoice. If false, the invoice’s state doesn’t automatically advance without an explicit action.
billing_reasonnullable enum Indicates the reason why the invoice was created.
automatic_pending_invoice_item_invoicemanualUnrelated to a subscription, for example created via the API or Dashboard.quote_acceptsubscriptionsubscription_createA new subscription was created.subscription_cycleA subscription advanced into a new period.subscription_thresholdA subscription reached a billing threshold.subscription_updateA subscription was updated.upcomingcollection_method enum Either charge_automatically or send_invoice. When charging automatically, Zoneless attempts to pay this invoice using the default payment method attached to the customer. When sending an invoice, Zoneless emails the customer with payment instructions.
charge_automaticallyAttempt payment using the default payment method attached to the customer.send_invoiceEmail payment instructions to the customer.created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
currency enum Three-letter currency code, in lowercase. For Zoneless, this is usdc.
Difference from Stripe: Uses usdc instead of fiat currency codes like usd.
customer string The ID of the customer to bill.
customer_emailnullable string The customer’s email. Until the invoice is finalized, this field equals customer.email. Once finalized, it is no longer updated.
customer_namenullable string The customer’s name. Until the invoice is finalized, this field equals customer.name. Once finalized, it is no longer updated.
descriptionnullable string An arbitrary string attached to the object. Often useful for displaying to users. Referenced as “memo” in the Dashboard.
due_datenullable timestamp The date on which payment for this invoice is due. This value is null for invoices where collection_method=charge_automatically.
hosted_invoice_urlnullable string The URL for the hosted invoice page, which allows customers to view and pay an invoice. null if the invoice has not been finalized yet.
invoice_pdfnullable string The link to download the PDF for the invoice. null if the invoice has not been finalized yet.
lines object The individual line items that make up the invoice. Sorted as: (1) pending invoice items (including prorations) in reverse chronological order, (2) subscription items in reverse chronological order, and (3) invoice items added after invoice creation in chronological order.
livemode boolean Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadatanullable object Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
numbernullable string A unique, identifying string that appears on emails sent to the customer for this invoice. Starts with the customer’s unique invoice_prefix if it is specified.
statusnullable enum The status of the invoice, one of draft, open, paid, uncollectible, or void.
draftopenpaiduncollectiblevoidstatus_transitions object The timestamps at which the invoice status was updated.
subtotal integer Total of all subscriptions, invoice items, and prorations on the invoice before any invoice-level discount or exclusive tax is applied. Item discounts are already incorporated.
total integer Total after discounts and taxes.
More attributes
{
"id": "in_z_1RvK8pQ2eZvKYlo2Hn4mWx9c",
"object": "invoice",
"account_country": "US",
"account_name": "Zoneless Docs",
"account_tax_ids": null,
"amount_due": 0,
"amount_paid": 0,
"amount_overpaid": 0,
"amount_remaining": 0,
"amount_shipping": 0,
"application": null,
"attempt_count": 0,
"attempted": false,
"auto_advance": false,
"automatic_tax": {
"enabled": false,
"liability": null,
"status": null
},
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created": 1723820400,
"currency": "usdc",
"custom_fields": null,
"customer": "cus_z_TpL8wQkR3nVmY",
"customer_address": null,
"customer_email": "maya.chen@example.com",
"customer_name": "Maya Chen",
"customer_phone": null,
"customer_shipping": null,
"customer_tax_exempt": "none",
"customer_tax_ids": [],
"confirmation_secret": null,
"default_payment_method": null,
"default_source": null,
"default_tax_rates": [],
"description": null,
"discounts": [],
"due_date": null,
"ending_balance": null,
"footer": null,
"from_invoice": null,
"hosted_invoice_url": null,
"invoice_pdf": null,
"issuer": {
"type": "self"
},
"last_finalization_error": null,
"latest_revision": null,
"lines": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
"url": "/v1/invoices/in_z_1RvK8pQ2eZvKYlo2Hn4mWx9c/lines"
},
"payments": {
"object": "list",
"data": [],
"has_more": false,
"total_count": 0,
"url": "/v1/invoice_payments"
},
"livemode": false,
"metadata": {},
"next_payment_attempt": null,
"number": null,
"on_behalf_of": null,
"parent": null,
"payment_settings": {
"default_mandate": null,
"payment_method_options": null,
"payment_method_types": null
},
"period_end": 1723820400,
"period_start": 1723820400,
"post_payment_credit_notes_amount": 0,
"pre_payment_credit_notes_amount": 0,
"receipt_number": null,
"shipping_cost": null,
"shipping_details": null,
"starting_balance": 0,
"statement_descriptor": null,
"status": "draft",
"status_transitions": {
"finalized_at": null,
"marked_uncollectible_at": null,
"paid_at": null,
"voided_at": null
},
"subtotal": 0,
"subtotal_excluding_tax": 0,
"test_clock": null,
"total": 0,
"total_discount_amounts": [],
"total_excluding_tax": 0,
"total_taxes": [],
"transfer_data": null,
"webhooks_delivered_at": 1723820400,
"platform_account": "acct_z_Platform123abc"
}