Invoice

An invoice represents an itemized bill sent by a company to a customer for a specific product and plan, tracking the amount owed, due date, and payment status.

Example

{
	"automatically_finalizes_at": "2023-12-01T05:00:00.401Z",
	"charge_buyer_fee": true,
	"collection_method": "send_invoice",
	"company": {
		"id": "biz_xxxxxxxxxxxxxx"
	},
	"created_at": "2023-12-01T05:00:00.401Z",
	"current_plan": {
		"currency": "usd",
		"description": "Monthly access to all premium analytics dashboards and data exports.",
		"formatted_price": "$10.00",
		"id": "plan_xxxxxxxxxxxxx"
	},
	"customer_name": "Jane Doe",
	"due_date": "2023-12-01T05:00:00.401Z",
	"email_address": "[e-mail]",
	"fetch_invoice_token": "eyJhbGciOiJIUzI1NiJ9...",
	"id": "inv_xxxxxxxxxxxxxx",
	"line_items": [
		{
			"label": "Platform subscription",
			"position": 42,
			"quantity": 6.9,
			"total": 6.9,
			"unit_price": 6.9
		}
	],
	"mailing_address": {
		"city": "<string>",
		"country": "<string>",
		"line1": "<string>",
		"line2": "<string>",
		"name": "<string>",
		"phone": "<string>",
		"postal_code": "<string>",
		"state": "<string>"
	},
	"member": {
		"id": "<string>"
	},
	"number": "#0001",
	"pay_online_url": "<string>",
	"payment": {
		"id": "pay_xxxxxxxxxxxxxx"
	},
	"payment_processing": true,
	"product": {
		"id": "prod_xxxxxxxxxxxxx",
		"title": "Pickaxe Analytics"
	},
	"status": "draft",
	"subscription_billing_anchor_at": "2023-12-01T05:00:00.401Z",
	"updated_at": "2023-12-01T05:00:00.401Z",
	"user": {
		"email": "[e-mail]",
		"id": "user_xxxxxxxxxxxxx",
		"name": "John Doe",
		"username": "johndoe42"
	}
}

automatically_finalizes_at · string<date-time> | null · required

The date and time when the invoice will be automatically finalized. For charge_automatically, triggers an automatic charge. For send_invoice, sends the invoice email at the specified time.

Example: 2023-12-01T05:00:00.401Z

charge_buyer_fee · boolean · required

Whether the invoice includes a buyer processing fee on top of the plan price.

collection_method · InvoiceCollectionMethods · required

The method used to collect payment for this invoice, such as automatic charging or manual payment.

Available options: send_invoice, charge_automatically

company · object · required

The company that issued this invoice.

Show child attributes

id · string · required

The unique identifier for the company.

Example: biz_xxxxxxxxxxxxxx

created_at · string<date-time> · required

The datetime the invoice was created.

Example: 2023-12-01T05:00:00.401Z

current_plan · object · required

The plan that this invoice charges for.

Show child attributes

currency · Currencies · required

The currency used for all prices on this plan (e.g., ‘usd’, ‘eur’). All monetary amounts on the plan are denominated in this currency.

Available options: usd, sgd, inr, aud, brl, cad, dkk, eur, nok, gbp, sek, chf, hkd, huf, jpy, mxn, myr, pln, czk, nzd, aed, eth, ape, cop, ron, thb, bgn, idr, dop, php, try, krw, twd, vnd, pkr, clp, uyu, ars, zar, dzd, tnd, mad, kes, kwd, jod, all, xcd, amd, bsd, bhd, bob, bam, khr, crc, xof, egp, etb, gmd, ghs, gtq, gyd, ils, jmd, mop, mga, mur, mdl, mnt, nad, ngn, mkd, omr, pyg, pen, qar, rwf, sar, rsd, lkr, tzs, ttd, uzs, rub, btc, cny, usdt, kzt, awg, whop_usd, xau

description · string | null · required

A text description of the plan visible to customers. Maximum 1000 characters. Null if no description is set.

Example: Monthly access to all premium analytics dashboards and da…

formatted_price · string · required

The formatted price (including currency) for the plan.

Example: $10.00

id · string · required

The unique identifier for the plan.

Example: plan_xxxxxxxxxxxxx

customer_name · string | null · required

The full name of the customer this invoice is addressed to. Null if no name is on file.

Example: Jane Doe

due_date · string<date-time> | null · required

The deadline by which payment is expected. Null if the invoice is collected automatically.

Example: 2023-12-01T05:00:00.401Z

email_address · string | null · required

The email address of the customer this invoice is addressed to. Null if no email is on file.

Example: [e-mail]

fetch_invoice_token · string · required

A signed token that allows fetching invoice data publicly without authentication.

Example: eyJhbGciOiJIUzI1NiJ9...

id · string · required

The unique identifier for the invoice.

Example: inv_xxxxxxxxxxxxxx

line_items · array<object> · required

Optional line items that break down the invoice total into individual charges.

Show child attributes

label · string · required

The label or description for this line item.

Example: Platform subscription

position · integer · required

The display order of this line item within the invoice.

Example: 42

quantity · number · required

The quantity of this line item.

Example: 6.9

total · number · required

The computed total for this line item (quantity * unit_price).

Example: 6.9

unit_price · number · required

The unit price for this line item.

Example: 6.9

mailing_address · object | null · required

The billing/mailing address associated with this invoice, if one was provided at creation time.

Show child attributes

city · string | null · required

The city of the address.

country · string | null · required

The country of the address.

line1 · string | null · required

The line 1 of the address.

line2 · string | null · required

The line 2 of the address.

name · string | null · required

The name of the customer.

phone · string | null · required

The phone number of the customer.

postal_code · string | null · required

The postal code of the address.

state · string | null · required

The state of the address.

member · object | null · required

The member that the invoice was created for. Null when the invoice is addressed to an email address with no member record behind it.

Show child attributes

id · string · required

The unique identifier for the company member.

number · string · required

The sequential invoice number for display purposes.

Example: #0001

pay_online_url · string | null · required

The checkout URL where the customer can pay this invoice online, with their email address pre-filled and locked.

payment · object | null · required

The payment that settled this invoice. Null while the invoice is unpaid, when the invoice was marked paid manually, and on a subscription renewal invoice, where the settling payment cannot yet be identified.

Show child attributes

id · string · required

The unique identifier for the payment.

Example: pay_xxxxxxxxxxxxxx

payment_processing · boolean · required

Whether a payment on this invoice is still clearing. True while a delayed payment method such as ACH or SEPA settles, during which the invoice stays open and is not marked past due.

product · object · required

The product that this invoice was generated for.

Show child attributes

id · string · required

The unique identifier for the product.

Example: prod_xxxxxxxxxxxxx

title · string · required

The display name of the product shown to customers on the product page and in search results.

Example: Pickaxe Analytics

status · InvoiceStatuses · required

The current payment status of the invoice, such as draft, open, paid, or void.

Available options: draft, open, paid, past_due, uncollectible, void

subscription_billing_anchor_at · string<date-time> | null · required

The date that defines when the subscription billing cycle starts. When set on a renewal plan invoice, all future billing periods anchor to this date.

Example: 2023-12-01T05:00:00.401Z

updated_at · string<date-time> · required

The datetime the invoice was last updated.

Example: 2023-12-01T05:00:00.401Z

user · object | null · required

The user this invoice is addressed to. Null if the user account has been removed.

Show child attributes

email · string | null · required

The user’s email address. Requires the member:email:read permission to access. Null if not authorized.

Example: [e-mail]

id · string · required

The unique identifier for the user.

Example: user_xxxxxxxxxxxxx

name · string | null · required

The user’s display name shown on their public profile.

Example: John Doe

username · string · required

The user’s unique username shown on their public profile.

Example: johndoe42