On this page
No Headings
An array of invoice-level details.
Note: This array does not return item details for the invoice.
arrayitemsobjectThe invoice details.
idstringThe ID of the invoice.
numberstringThe invoice number. If you omit this value, the default is the number that the API automatically increments from the last number.
statusstring"DRAFT", "UNPAID", "SENT", "SCHEDULED", "PARTIALLY_PAID", "PAYMENT_PENDING", "PAID", "MARKED_AS_PAID", "CANCELLED", "REFUNDED", "PARTIALLY_REFUNDED", "MARKED_AS_REFUNDED"The invoice status. When you search for invoices, you must specify this value as an array. For example, "status": ["REFUNDED"]. The status indicates the phase of an invoice in its lifecycle. The status also indicates whether the invoice is unpaid, partially paid, fully paid, partially refunded, or fully refunded. An invoice payment can be either:
Connected to an invoice. The customer clicks Pay on the invoice to make a payment. The payment is automatically recorded.
Disconnected from an invoice. The customer pays by check, wire transfer, or another method. The merchant manually records the payment.
| Status | Occurs when |
|---|---|
DRAFT | A merchant creates a draft invoice. Note: A customer cannot pay an invoice with this status. A customer cannot pay an invoice until it has a status of |
UNPAID | A merchant chooses to suppress the PayPal email notification when he or she sends the invoice through the API or the Create Invoice page, and then manually sends the invoice link in his or her own email. To send an invoice without email notification, the merchant either:
|
SENT | A merchant accepts the default PayPal email notification when he or she sends the invoice through the API or the Create Invoice page. PayPal automatically emails the invoice to the customer and a Pay button appears on the invoice, which enables the customer to pay the invoice. In a web app, the invoice appears as |
SCHEDULED | A merchant schedules an invoice to send on a future date. At 07:00 on that date in the preferred time zone of the merchant's PayPal account profile, PayPal emails an invoice notification to the merchant and the customer, adds an online payment button to the customer’s view of the invoice, and updates the invoice status to |
PARTIALLY_PAID | A customer makes a partial payment for the invoice through one of these methods:
|
PAYMENT_PENDING | A customer pays an invoice but the payment is pending for one of these reasons:
Note: Most payments never go into a payment-pending state. |
PAID | A customer fully pays the invoice through one of these methods:
|
MARKED_AS_PAID | A customer makes a disconnected payment for the balance of the invoice. The merchant manually marks the invoice as paid. |
CANCELLED | A merchant or customer cancels a sent invoice. You can cancel an invoice in |
REFUNDED | A merchant fully refunds an invoice through one these methods:
|
PARTIALLY_REFUNDED | A merchant partially refunds an invoice through one or both of these methods:
|
MARKED_AS_REFUNDED | A merchant makes a disconnected refund, such as a check payment, for the invoice balance and manually marks the invoice as fully refunded. Note: A merchant can only mark a marked-as-paid invoice as refunded. |
merchant_inforequiredobjectThe merchant information, such as business name, email, address, and so on.
emailstringemailThe merchant email address. This email must be listed in the merchant's PayPal profile.
If you omit this value, notifications are sent from and to the primary email address but do not appear on the invoice.
business_namestringThe merchant's business name.
first_namestringThe merchant's first name.
last_namestringThe merchant's last name.
addressobjectThe merchant's address.
line1requiredstringThe first line of the address. For example, number or street.
line2stringThe second line of the address. For example, suite or apartment number.
cityrequiredstringThe city name.
country_coderequiredstringThe two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas is used in that country's top-level domain names. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
postal_codestringThe postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
statestringphonestringphoneThe phone number, in its canonical international E.164 numbering plan format.
phoneobjectThe merchant's phone number.
country_codestring^[0-9]{1,3}?$The country code portion of the phone number, in E.164 format.
national_numberstring^[0-9]{1,14}?$The in-country phone number, in E.164 format.
faxobjectThe merchant's fax number.
country_codestring^[0-9]{1,3}?$The country code portion of the phone number, in E.164 format.
national_numberstring^[0-9]{1,14}?$The in-country phone number, in E.164 format.
websitestringuriThe merchant's website.
tax_idstringThe merchant's tax ID.
additional_infostringAny additional information, such as business hours.
billing_infoarrayAn array of billing information for the invoice recipient.
Note: This value is an array with only one element.
itemsobjectThe billing information for the invoice recipient.
emailstringemailThe invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent.
phoneobjectThe invoice recipient's phone number.
country_codestring^[0-9]{1,3}?$The country code portion of the phone number, in E.164 format.
national_numberstring^[0-9]{1,14}?$The in-country phone number, in E.164 format.
first_namestringThe invoice recipient's first name.
last_namestringThe invoice recipient's last name.
business_namestringThe invoice recipient's business name.
addressobjectThe invoice recipient's billing address.
line1requiredstringThe first line of the address. For example, number or street.
line2stringThe second line of the address. For example, suite or apartment number.
cityrequiredstringThe city name.
country_coderequiredstringThe two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas is used in that country's top-level domain names. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
postal_codestringThe postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
statestringphonestringphoneThe phone number, in its canonical international E.164 numbering plan format.
languagestring"da_DK", "de_DE", "en_AU", "en_GB", "en_US", "es_ES", "es_XC", "fr_CA", "fr_FR", "fr_XC", "he_IL", "id_ID", "it_IT", "ja_JP", "nl_NL", "no_NO", "pl_PL", "pt_BR", "pt_PT", "ru_RU", "sv_SE", "th_TH", "tr_TR", "zh_CN", "zh_HK", "zh_TW", "zh_XC"The language in which the invoice recipient's email appears. Used only when the recipient does not have a PayPal account.
If you omit the language and the recipient does not have a PayPal account, the email is sent in the language of the merchant's PayPal account.
additional_infostringAny additional information about the recipient.
shipping_infoobjectThe shipping information for the recipient of the invoice.
first_namestringThe first name of the recipient at the shipping address.
last_namestringThe last name of the recipient at the shipping address.
business_namestringThe business name of the recipient at the shipping address.
addressobjectThe shipping address.
line1requiredstringThe first line of the address. For example, number or street.
line2stringThe second line of the address. For example, suite or apartment number.
cityrequiredstringThe city name.
country_coderequiredstringThe two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGBand notUKas is used in that country's top-level domain names. Use theC2country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
postal_codestringThe postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.
statestringphonestringphoneThe phone number, in its canonical international E.164 numbering plan format.
cc_infoarrayAn array of email addresses to which PayPal sends a copy of the invoice.
itemsobjectThe participant information.
emailrequiredstringemailThe email address of the person who receives a copy of the invoice.
itemsarrayAn array of invoice line item information.
itemsobjectThe invoice line item information.
namerequiredstringThe item name.
descriptionstringThe item description.
quantityrequirednumberThe item quantity. Value is from -10000 to 10000. Supports up to five decimal places.
unit_pricerequiredobjectThe currency and amount of the item unit price. Value is from -1000000 to 1000000. Supports up to two decimal places.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.taxobjectThe tax information.
namerequiredstringThe tax name.
percentrequirednumberThe tax rate. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount of the calculated tax.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.tax_notestring^[\s\S]*$The tax note used to track the tax related data.
datestringdateThe date when the item or service was provided, in Internet date and time format. For example, yyyy-MM-dd z.
discountobjectThe item discount, as a percent or an amount value.
percentnumberThe discount as a percentage value. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount of the invoice-level discount. Value is from 0 to 1000000. Supports up to two decimal places.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.unit_of_measurestring"QUANTITY", "HOURS", "AMOUNT"The unit of measure for the invoiced item. For AMOUNT the unit_price and quantity are not shown on the invoice.
Note: If your specify different unit_of_measure values for the same invoice, the invoice uses the first value.invoice_datestringdateThe invoice date as specified by the sender, in Internet date and time format.
payment_termobjectThe payment due date of the invoice. If you include due_date, the term_type value is ignored.
term_typestring"DUE_ON_RECEIPT", "DUE_ON_DATE_SPECIFIED", "NET_10", "NET_15", "NET_30", "NET_45", "NET_60", "NET_90", "NO_DUE_DATE"The term when the invoice payment is due.
due_datestringdateThe date when the invoice payment is due, in Internet date and time format. For example, yyyy-MM-dd z.
referencestringThe reference data, such as PO number.
discountobjectThe invoice level discount, as a percent or an amount value.
percentnumberThe discount as a percentage value. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount of the invoice-level discount. Value is from 0 to 1000000. Supports up to two decimal places.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.shipping_costobjectThe shipping amount, as a percent or an amount value.
amountobjectThe currency and amount of the shipping charge. Value is from 0 to 1000000. Supports up to two decimal places.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.taxobjectThe tax percentage on the shipping amount.
namerequiredstringThe tax name.
percentrequirednumberThe tax rate. Value is from 0 to 100. Supports up to five decimal places.
amountobjectThe currency and amount of the calculated tax.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.tax_notestring^[\s\S]*$The tax note used to track the tax related data.
customobjectThe custom amount to apply to an invoice. If you include a label, you must include a custom amount.
labelstringThe custom amount label.
amountobjectThe currency and amount of the custom value. Value is from -1000000 to 1000000. Supports up to two decimal places.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.allow_partial_paymentbooleanfalseIndicates whether the invoice allows a partial payment. If false, the invoice must be paid in full. If true, the invoice allows partial payments.
Note: This feature is not available for merchants inIndia,Brazil, orIsrael.
minimum_amount_dueobjectThe minimum amount allowed for a partial payment. Valid only if allow_partial_payment is true.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.tax_calculated_after_discountbooleanfalseIndicates whether the tax is calculated before or after a discount. If false, the tax is calculated before a discount. If true, the tax is calculated after a discount.
tax_inclusivebooleanfalseIndicates whether the unit price includes tax.
termsstringThe general terms of the invoice.
notestringA note to the invoice recipient. The note also appears on the invoice notification email.
merchant_memostringA private bookkeeping memo for the merchant.
logo_urlstringuriThe full URL to an external logo image. The logo must not be larger than 250 pixels wide by 90 pixels high. The logo must be stored on a secure server.
total_amountobjectThe total amount of the invoice.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.paymentsarrayAn array of payment details for the invoice.
itemsobjectThe payment details.
typestring"PAYPAL", "EXTERNAL"The payment type in an invoicing flow. The record refund method supports the EXTERNAL refund type. The PAYPAL refund type is supported for backward compatibility.
transaction_idstringThe ID for a PayPal payment transaction. Required for the PAYPAL payment type.
transaction_typestring"SALE", "AUTHORIZATION", "CAPTURE"The transaction type.
datestringdate-timeThe date when the invoice was paid, in Internet date and time format.
methodrequiredstring"BANK_TRANSFER", "CASH", "CHECK", "CREDIT_CARD", "DEBIT_CARD", "PAYPAL", "WIRE_TRANSFER", "OTHER"The payment mode or method.
notestringA note associated with the payment.
amountobjectThe payment amount to record against the invoice. If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.refundsarrayAn array of refund details for the invoice.
itemsobjectThe invoicing refund details.
typestring"PAYPAL", "EXTERNAL"The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the EXTERNAL refund type. The PAYPAL refund type is supported for backward compatibility.
transaction_idstringThe ID of the PayPal refund transaction. Required for the PAYPAL refund type.
datestringdate-timeThe date when the invoice was refunded, in Internet date and time format. For example, 2014-02-27 PST.
notestringA note associated with the refund.
amountobjectThe currency and amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.metadataobjectThe audit information for the invoice.
created_datestringdate-timeThe date and time when the resource was created, in Internet date and time format.
created_bystringThe email address of the account that created the resource.
cancelled_datestringdate-timeThe date and time when the resource was canceled, in Internet date and time format.
cancelled_bystringThe actor who canceled the resource.
last_updated_datestringdate-timeThe date and time when the resource was last edited, in Internet date and time format.
last_updated_bystringThe email address of the account that last edited the resource.
first_sent_datestringdate-timeThe date and time when the resource was first sent, in Internet date and time format.
last_sent_datestringdate-timeThe date and time when the resource was last sent, in Internet date and time format.
last_sent_bystringThe email address of the account that last sent the resource.
payer_view_urlstringuriThe URL for the payer's view of the invoice.
paid_amountobjectThe payment summary of the invoice. Includes the amount paid through PayPal and other sources.
paypalobjectThe currency and amount of the total paid or refunded through PayPal.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.otherobjectThe currency and amount of the total paid or refunded through other sources.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.refunded_amountobjectThe payment summary of the invoice. Includes the amount refunded through PayPal and other sources.
paypalobjectThe currency and amount of the total paid or refunded through PayPal.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.otherobjectThe currency and amount of the total paid or refunded through other sources.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.attachmentsarrayAn array of PayPal file IDs for the files that are attached to an invoice. You can attach up to five files.
itemsobjectThe file that is attached to an invoice or template.
namestringThe name of the attached file.
urlstringuriThe URL of the attached file. Use this URL to download the file.
allow_tipbooleanfalseIndicates whether the invoice enables the customer to enter a tip amount during payment. If true, the invoice shows a tip amount field so that the customer can enter a tip amount. If false, the invoice does not show a tip amount field.
Note: This feature is not available for merchants inHong Kong,Taiwan,India, orJapan.
template_idstring"PayPal system template"This value is only used to determine the layout to display on the create or edit invoice experience, such as which fields to show and hide. It does not impact the view of the invoice that the customer receives.
Note: If you are just using the Invoicing APIs to create and send invoices, leave this field blank. The template_id is only needed if you use the Invoicing API to build a full invoicing solution that includes templates.linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstring^[\S\s]*$The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
relrequiredstring^[\S\s]*$The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"The HTTP method required to make the related call.
titlestring^[\S\s]*$The link title.
mediaTypestring^[\S\s]*$The media type, as defined by RFC 2046. Describes the link target.
encTypestring^[\S\s]*$"application/json"The media type in which to submit the request data.
schemaobjectThe schema that describes the request data.
additionalItemsobjectAny additional items.
dependenciesobjectAny Dependencies.
itemsobjectAn item.
patternPropertiesobjectThe pattern properties.
propertiesobjectProperties.
allOfarrayAn array of sub-schemas. The data must validate against all sub-schemas.
itemsobjectA sub-schema against which the data must validate.
anyOfarrayAn array of sub-schemas. The data must validate against one or more sub-schemas.
itemsobjectA sub-schema against which the data must validate.
oneOfarrayAn array of sub-schemas. The data must validate against one sub-schema.
itemsobjectA sub-schema against which the data must validate.
notobjectNot.
linksarrayAn array of links.
itemsobjectA link.
fragmentResolutionstring^[\S\s]*$The fragment resolution.
mediaobjectThe media type and context-encoding scheme.
typestring^[\S\s]*$The media type. See Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.
binaryEncodingstring^[\S\s]*$The content-encoding scheme. See Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies.
pathStartstringuriTo apply this schema to the instances' URIs, start the URIs with this value.
targetSchemaobjectThe schema that describes the link target.
additionalItemsobjectAny additional items.
dependenciesobjectAny Dependencies.
itemsobjectAn item.
patternPropertiesobjectThe pattern properties.
propertiesobjectProperties.
allOfarrayAn array of sub-schemas. The data must validate against all sub-schemas.
itemsobjectA sub-schema against which the data must validate.
anyOfarrayAn array of sub-schemas. The data must validate against one or more sub-schemas.
itemsobjectA sub-schema against which the data must validate.
oneOfarrayAn array of sub-schemas. The data must validate against one sub-schema.
itemsobjectA sub-schema against which the data must validate.
notobjectNot.
linksarrayAn array of links.
itemsobjectA link.
fragmentResolutionstring^[\S\s]*$The fragment resolution.
mediaobjectThe media type and context-encoding scheme.
typestring^[\S\s]*$The media type. See Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.
binaryEncodingstring^[\S\s]*$The content-encoding scheme. See Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies.
pathStartstringuriTo apply this schema to the instances' URIs, start the URIs with this value.