On this page
No Headings
objectidstringThe unique identifier of the invoice
billing_entity_codestring^[a-zA-Z0-9_-]*$Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.
sequential_idintegerSequential ID of the invoice, unique within the billing entity.
statusstring | null"DRAFT", "FINALIZED"Status of the invoice
payment_statusstring"PENDING", "FAILED", "SUCCEEDED"Status of invoice payment
amountobjectTotal amount due for the invoice, including breakdown of fees, taxes, and discounts.
total_amountobjectbreakdownobjectfeesobjectThe total amount of fees applied to the invoice.
credit_notesobjectThe total amount of credit notes applied to the invoice.
sub_total_excluding_taxesobjectThe subtotal amount of the invoice excluding taxes.
taxesobjectThe total amount of taxes applied to the invoice.
sub_total_including_taxesobjectThe subtotal amount of the invoice including taxes.
prepaid_creditobjectThe total amount of prepaid credits applied to the invoice.
progressive_billing_creditobjectThe total amount of progressive billing credits applied to the invoice.
feesarrayitemsobjectidstring | nulluuidUnique identifier assigned to the fee. This ID is exclusively and serves as a unique identifier for the fee's record.
total_amountobjectThe cost of this specific fee, including any applicable taxes.
valuerequirednumberdecimal0The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
currency_coderequiredstring^[A-Z]{3}$Currency code in ISO 4217 format.
namestring | nullThe the name of the fee associated to any one of the charge, the credit, the subscription or the commitment
due_dateobjectdate^(?:[1-9]\d{3}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|02-(?:0[1-9]|1\d|2[0-8]))|(?:(?:\d{2}(?:0[48]|[2468][048]|[13579][26]))|(?:[02468][048]00|[13579][26]00))-02-29)$Due date for the invoice payment
issued_dateobjectdate^(?:[1-9]\d{3}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|02-(?:0[1-9]|1\d|2[0-8]))|(?:(?:\d{2}(?:0[48]|[2468][048]|[13579][26]))|(?:[02468][048]00|[13579][26]00))-02-29)$Date when the invoice was issued
invoice_numberstringInvoice number, unique within the billing entity.
version_numberstringnumberVersion number of the invoice, indicating the revision of the invoice.
payment_overduebooleanIndicates whether the invoice payment is overdue.
invoice_typestring | null"SUBSCRIPTION", "ONE_OFF", "CREDIT"Type of invoice
customerobjectA customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.
namerequiredstringFull name of the customer
external_idrequiredstring^[a-zA-Z0-9_-]*$External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.
emailrequiredstring^.+@[^"\-].+$The internationalized email address.
billing_entity_codestring^[a-zA-Z0-9_-]*$Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.
addressobjectAddress of the customer or party.
line1stringFirst line of the address.
line2stringSecond line of the address (optional). This can include apartment, suite, or unit numbers.
citystringCity of the customer or party.
statestringState or region of the customer or party.
postal_codestringPostal or ZIP code of the customer or party. Typically required for countries with a postal code or an equivalent.
countrystring^[A-Z]{2}$Country of the customer or party. Use ISO 3166-1 alpha-2 country codes.
phonestringphonePrimary phone number of the customer, including country code if available.
payment_method_tokenobjectToken representing the customer's saved payment method in PayPal Vault.
payment_method_typestring"CARD", "PAYPAL", "ACH_DEBIT", "APPLE_PAY"Type of payment method used (e.g., CARD, ACH_DEBIT)
taxesarrayList of tax entities configured for the customer.
itemsobjectRepresents a customizable tax rate that can be applied to invoices and fees
namerequiredstringName of the tax
ratestring^(?!0+(?:\.0+)?$)(?:0?\.\d{1,2}|[1-9]\d?(?:\.\d{1,2})?|100(?:\.0{1,2})?)$The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx.
descriptionstringDetailed description of the tax for internal reference
codestring^[a-zA-Z0-9_-]*$Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens.
idstringuuidUnique identifier of the tax
created_atobjectdate-timeDate and time in ISO 8601 format.
The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format
metadataarrayitemsobjectSet of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format
keyrequiredstringThe metadata object key
valuerequiredstringThe metadata object value
display_in_invoicerequiredbooleanDetermines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice.
idstringbilling_periodarrayitemsobjectsubscription_idstringUnique identifier for the subscription
external_subscription_idstringThe subscription external unique identifier supplied by client.
plan_idstringUnique identifier for the plan
payment_method_tokenobjectToken representing the customer's payment method
payment_method_typeobject"CARD", "PAYPAL", "ACH_DEBIT", "APPLE_PAY"Type of payment method used (e.g., CARD, ACH_DEBIT)
subscription_from_datetimeobjectdate-timeDate and time in ISO 8601 format.
subscription_to_datetimeobjectdate-timeDate and time in ISO 8601 format.
charges_from_datetimeobjectdate-timeDate and time in ISO 8601 format.
charges_to_datetimeobjectdate-timeDate and time in ISO 8601 format.
invoicing_reasonstringReason for invoicing, e.g., 'subscription', 'usage', 'one-time charge'
created_atobjectdate-timeDate and time in ISO 8601 format.
updated_atobjectdate-timeDate and time in ISO 8601 format.
applied_taxesarrayitemsobjectidstringuuidUnique identifier of the applied tax.
tax_idstringuuidUnique identifier of the tax.
tax_namestringName of the tax.
tax_codestringUnique code used to identify the tax associated with the API request.
tax_ratenumberThe percentage rate of the tax
tax_descriptionstringInternal description of the taxes
amountobjectAmount of the tax
valuerequirednumberdecimal0The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
currency_coderequiredstring^[A-Z]{3}$Currency code in ISO 4217 format.
created_atstringdate-timeThe date and time when the applied tax was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the applied tax was initially created.
fees_amountobjectThe total fees amount to which the tax is applied.
valuerequirednumberdecimal0The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).