Invoice data model

View field support, webhooks, and list parameters for each integration on the Supported Integrations page.

FieldTypeRequiredDescription
idstringNo
created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
due_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
paid_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
refunded_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
cancelled_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
posted_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
total_amountnumberNo
paid_amountnumberNo
refund_amountnumberNo
tax_amountnumberNo
discount_amountnumberNo
balance_amountnumberNo
invoice_numberstringNoExternal identifier (ie. reference) for this invoice
referencestringNo
contact_idstringNo(reference to AccountingContact)
currencystringNo
notesstringNo
extended_notesAccountingExtendedNote[]No
extended_notes[].notestringNo
extended_notes[].userAccountingExtendedNote_userNo
extended_notes[].user.idstringNo
extended_notes[].user.namestringNo
extended_notes[].datestring (date-time)No
extended_notes[].visibilityenumNoValues: PUBLIC, PRIVATE
refund_reasonstringNo
termenumNo@deprecated use payment_terms instead Values: ON_RECEIPT, NET_7, NET_10, NET_15, NET_20, NET_25, NET_30, NET_45, NET_60, NET_90, OTHER
payment_termsenumNoValues: ON_RECEIPT, NET_7, NET_10, NET_15, NET_20, NET_25, NET_30, NET_45, NET_60, NET_90, OTHER
paymentterm_idstringNo
lineitemsAccountingLineitem[]No
lineitems[].idstringNo
lineitems[].created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
lineitems[].updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
lineitems[].refunded_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
lineitems[].total_amountnumberNounit_quantity * unit_amount + tax_amount
lineitems[].refund_amountnumberNo
lineitems[].discount_amountnumberNo
lineitems[].tax_amountnumberNo
lineitems[].item_idstringNo(reference to CommerceItem)
lineitems[].unit_amountnumberNo
lineitems[].unit_quantitynumberNo
lineitems[].item_skustringNo
lineitems[].item_namestringNo
lineitems[].item_descriptionstringNo
lineitems[].notesstringNo
lineitems[].taxrate_idstringNo
lineitems[].account_idstringNo(reference to AccountingAccount)
lineitems[].category_idsstring[]No(reference to AccountingCategory)
lineitems[].locationsAccountingReference[]No
lineitems[].locations[].idstringNo
lineitems[].locations[].namestringNo
lineitems[].item_variantsAccountingReference[]No
lineitems[].item_variants[].idstringNo
lineitems[].item_variants[].namestringNo
lineitems[].feesAccountingFee[]No
lineitems[].fees[].typeenumYesUnified fee category Values: TAX, DISCOUNT, PROMOTION, SHIPPING, GIFT_WRAP, COD, SURCHARGE, TIP, SERVICE_CHARGE, OTHER
lineitems[].fees[].original_typestringNoThe provider's original fee label, e.g. "VAT" or a shipping carrier name
lineitems[].fees[].amountnumberYes
lineitems[].fees[].currencystringNoISO 4217 currency code, e.g. USD
lineitems[].contact_idstringNo(reference to AccountingContact)
lineitems[].project_idstringNoref -> AccountingProject; the project this line is coded to (reference to TaskProject)
lineitems[].exchange_ratenumberNoThe exchange rate applied to this line, for multi-currency documents
lineitems[].is_billablebooleanNoTrue when the line is rebillable to a customer
statusenumNoValues: DRAFT, VOIDED, AUTHORIZED, PAID, PARTIALLY_PAID, PARTIALLY_REFUNDED, REFUNDED, SUBMITTED, DELETED, OVERDUE
urlstringNoThe public URL for the invoice to send to a customer to view or pay.
payment_collection_methodenumNoWhen set to charging_automatically, an automated attempt will occur to pay this invoice using the default payment source attached to the contactcustomer. When set to send_invoice, an will email will be sent with this invoice to the contact/customer with payment instructions. Values: send_invoice, charge_automatically
typeenumNoBILL removed (use AccountingBill); remaining values: INVOICE, CREDITMEMO Values: INVOICE, CREDITMEMO
attachmentsAccountingAttachment[]No
attachments[].idstringNo
attachments[].download_urlstringNo
attachments[].namestringNo
attachments[].mime_typestringNo
sendbooleanNo
organization_idstringNo
paymentsAccountingPaymentReference[]Noead-only reciprocal of PaymentPayment.allocations; payments applied to this invoice
payments[].payment_idstringNoreferences a PaymentPayment that was applied to this object (reference to PaymentPayment)
payments[].amountnumberNoamount of the payment applied to this object
payments[].allocated_atstring (date-time)NoDate and time when the payment was applied, in ISO 8601 format and UTC (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
category_idsstring[]No(reference to AccountingCategory)
project_idstringNo(reference to TaskProject)
metadataAccountingMetadata[]No
metadata[].idstringNo
metadata[].slugstringNo
metadata[].valueobjectNo
metadata[].namespacestringNo
metadata[].formatenumNoValues: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNo
sub_total_amountnumberNoTotal before tax
exchange_ratenumberNoExchange rate to the base/home currency at the document date
is_inclusive_of_taxbooleanNoTrue when the document amounts already include tax
salesorder_idsstring[]Norefs -> AccountingSalesorder; the sales orders this invoice was raised from

TypeScript

TypeScript
export type AccountingInvoice = {
	id?: string;
	created_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	updated_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	due_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	paid_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	refunded_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	cancelled_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	posted_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	total_amount?: number;
	paid_amount?: number;
	refund_amount?: number;
	tax_amount?: number;
	discount_amount?: number;
	balance_amount?: number;
	invoice_number?: string; // External identifier (ie. reference) for this invoice
	reference?: string;
	contact_id?: string; // (reference to AccountingContact)
	currency?: string;
	notes?: string;
	extended_notes?: [];
	refund_reason?: string;
	term?: 'ON_RECEIPT' | 'NET_7' | 'NET_10' | 'NET_15' | 'NET_20' | 'NET_25' | 'NET_30' | 'NET_45' | 'NET_60' | 'NET_90' | 'OTHER'; // @deprecated use payment_terms instead
	payment_terms?: 'ON_RECEIPT' | 'NET_7' | 'NET_10' | 'NET_15' | 'NET_20' | 'NET_25' | 'NET_30' | 'NET_45' | 'NET_60' | 'NET_90' | 'OTHER';
	paymentterm_id?: string;
	lineitems?: [];
	status?: 'DRAFT' | 'VOIDED' | 'AUTHORIZED' | 'PAID' | 'PARTIALLY_PAID' | 'PARTIALLY_REFUNDED' | 'REFUNDED' | 'SUBMITTED' | 'DELETED' | 'OVERDUE';
	url?: string; // The public URL for the invoice to send to a customer to view or pay.
	payment_collection_method?: 'send_invoice' | 'charge_automatically'; // When set to charging_automatically, an automated attempt will occur to pay this invoice using the default payment source attached to the contactcustomer. When set to send_invoice, an will email will be sent with this invoice to the contact/customer with payment instructions.
	type?: 'INVOICE' | 'CREDITMEMO'; // BILL removed (use AccountingBill); remaining values: INVOICE, CREDITMEMO
	attachments?: [];
	send?: boolean;
	organization_id?: string;
	payments?: []; // ead-only reciprocal of PaymentPayment.allocations; payments applied to this invoice
	category_ids?: string[]; // (reference to AccountingCategory)
	project_id?: string; // (reference to TaskProject)
	metadata?: [];
	sub_total_amount?: number; // Total before tax
	exchange_rate?: number; // Exchange rate to the base/home currency at the document date
	is_inclusive_of_tax?: boolean; // True when the document amounts already include tax
	salesorder_ids?: string[]; // refs -> AccountingSalesorder; the sales orders this invoice was raised from
	raw?: any;
} 

Zod

Zod
import { z } from 'zod';

export const ZodAccountingInvoice = z.object({
	id: z.string().optional(),
	created_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	updated_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	due_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	paid_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	refunded_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	cancelled_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	posted_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	total_amount: z.number().optional(),
	paid_amount: z.number().optional(),
	refund_amount: z.number().optional(),
	tax_amount: z.number().optional(),
	discount_amount: z.number().optional(),
	balance_amount: z.number().optional(),
	invoice_number: z.string().optional().describe("External identifier (ie. reference) for this invoice"),
	reference: z.string().optional(),
	contact_id: z.string().optional().describe("(reference to AccountingContact)"),
	currency: z.string().optional(),
	notes: z.string().optional(),
	extended_notes: z.array().optional(),
	refund_reason: z.string().optional(),
	term: z.enum("ON_RECEIPT", "NET_7", "NET_10", "NET_15", "NET_20", "NET_25", "NET_30", "NET_45", "NET_60", "NET_90", "OTHER").optional().describe("@deprecated use payment_terms instead"),
	payment_terms: z.enum("ON_RECEIPT", "NET_7", "NET_10", "NET_15", "NET_20", "NET_25", "NET_30", "NET_45", "NET_60", "NET_90", "OTHER").optional(),
	paymentterm_id: z.string().optional(),
	lineitems: z.array().optional(),
	status: z.enum("DRAFT", "VOIDED", "AUTHORIZED", "PAID", "PARTIALLY_PAID", "PARTIALLY_REFUNDED", "REFUNDED", "SUBMITTED", "DELETED", "OVERDUE").optional(),
	url: z.string().optional().describe("The public URL for the invoice to send to a customer to view or pay."),
	payment_collection_method: z.enum("send_invoice", "charge_automatically").optional().describe("When set to charging_automatically, an automated attempt will occur to pay this invoice using the default payment source attached to the contactcustomer. When set to send_invoice, an will email will be sent with this invoice to the contact/customer with payment instructions."),
	type: z.enum("INVOICE", "CREDITMEMO").optional().describe("BILL removed (use AccountingBill); remaining values: INVOICE, CREDITMEMO"),
	attachments: z.array().optional(),
	send: z.boolean().optional(),
	organization_id: z.string().optional(),
	payments: z.array().optional().describe("ead-only reciprocal of PaymentPayment.allocations; payments applied to this invoice"),
	category_ids: z.array().optional().describe("(reference to AccountingCategory)"),
	project_id: z.string().optional().describe("(reference to TaskProject)"),
	metadata: z.array().optional(),
	sub_total_amount: z.number().optional().describe("Total before tax"),
	exchange_rate: z.number().optional().describe("Exchange rate to the base/home currency at the document date"),
	is_inclusive_of_tax: z.boolean().optional().describe("True when the document amounts already include tax"),
	salesorder_ids: z.array().optional().describe("refs -> AccountingSalesorder; the sales orders this invoice was raised from"),

});

Python

Python
import dataclasses

@dataclasses.dataclass
class AccountingInvoiceTerm(str, Enum):
	ON_RECEIPT = 'ON_RECEIPT'
	NET_7 = 'NET_7'
	NET_10 = 'NET_10'
	NET_15 = 'NET_15'
	NET_20 = 'NET_20'
	NET_25 = 'NET_25'
	NET_30 = 'NET_30'
	NET_45 = 'NET_45'
	NET_60 = 'NET_60'
	NET_90 = 'NET_90'
	OTHER = 'OTHER'

@dataclasses.dataclass
class AccountingInvoicePayment_terms(str, Enum):
	ON_RECEIPT = 'ON_RECEIPT'
	NET_7 = 'NET_7'
	NET_10 = 'NET_10'
	NET_15 = 'NET_15'
	NET_20 = 'NET_20'
	NET_25 = 'NET_25'
	NET_30 = 'NET_30'
	NET_45 = 'NET_45'
	NET_60 = 'NET_60'
	NET_90 = 'NET_90'
	OTHER = 'OTHER'

@dataclasses.dataclass
class AccountingInvoiceStatus(str, Enum):
	DRAFT = 'DRAFT'
	VOIDED = 'VOIDED'
	AUTHORIZED = 'AUTHORIZED'
	PAID = 'PAID'
	PARTIALLY_PAID = 'PARTIALLY_PAID'
	PARTIALLY_REFUNDED = 'PARTIALLY_REFUNDED'
	REFUNDED = 'REFUNDED'
	SUBMITTED = 'SUBMITTED'
	DELETED = 'DELETED'
	OVERDUE = 'OVERDUE'

@dataclasses.dataclass
class AccountingInvoicePayment_collection_method(str, Enum):
	send_invoice = 'send_invoice'
	charge_automatically = 'charge_automatically'

@dataclasses.dataclass
class AccountingInvoiceType(str, Enum):
	INVOICE = 'INVOICE'
	CREDITMEMO = 'CREDITMEMO'

@dataclasses.dataclass
class AccountingInvoice:
	id: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	created_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	updated_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	due_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	paid_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	refunded_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	cancelled_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	posted_at: Optional[str]
	total_amount: Optional[int]
	paid_amount: Optional[int]
	refund_amount: Optional[int]
	tax_amount: Optional[int]
	discount_amount: Optional[int]
	balance_amount: Optional[int]
	"""External identifier (ie. reference) for this invoice"""
	invoice_number: Optional[str]
	reference: Optional[str]
	"""(reference to AccountingContact)"""
	contact_id: Optional[str]
	currency: Optional[str]
	notes: Optional[str]
	extended_notes: Optional[PropertyAccountingInvoiceExtended_notes]
	refund_reason: Optional[str]
	"""@deprecated use payment_terms instead"""
	term: Optional[AccountingInvoiceTerm]
	payment_terms: Optional[AccountingInvoicePayment_terms]
	paymentterm_id: Optional[str]
	lineitems: Optional[PropertyAccountingInvoiceLineitems]
	status: Optional[AccountingInvoiceStatus]
	"""The public URL for the invoice to send to a customer to view or pay."""
	url: Optional[str]
	"""When set to charging_automatically, an automated attempt will occur to pay this invoice using the default payment source attached to the contactcustomer. When set to send_invoice, an will email will be sent with this invoice to the contact/customer with payment instructions."""
	payment_collection_method: Optional[AccountingInvoicePayment_collection_method]
	"""BILL removed (use AccountingBill); remaining values: INVOICE, CREDITMEMO"""
	type: Optional[AccountingInvoiceType]
	attachments: Optional[PropertyAccountingInvoiceAttachments]
	send: Optional[bool]
	organization_id: Optional[str]
	"""ead-only reciprocal of PaymentPayment.allocations; payments applied to this invoice"""
	payments: Optional[PropertyAccountingInvoicePayments]
	"""(reference to AccountingCategory)"""
	category_ids: Optional[List[List[str]]]
	"""(reference to TaskProject)"""
	project_id: Optional[str]
	metadata: Optional[PropertyAccountingInvoiceMetadata]
	"""Total before tax"""
	sub_total_amount: Optional[int]
	"""Exchange rate to the base/home currency at the document date"""
	exchange_rate: Optional[int]
	"""True when the document amounts already include tax"""
	is_inclusive_of_tax: Optional[bool]
	"""refs -> AccountingSalesorder; the sales orders this invoice was raised from"""
	salesorder_ids: Optional[List[List[str]]]
Are we missing anything? Let us know
Was this page helpful?