invoice_list

An array of invoice-level details.

Note: This array does not return item details for the invoice.

An array of invoice objects.

statusenumOptional

The invoice status. When you [search for invoices](/docs/api/invoicing/v1/#search_search), 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.

Similarly, an invoice refund can be disconnected from an invoice. The merchant refunds a payment by check, wire transfer, or another method and manually records the refund. This table lists the typical order through which an invoice moves through status values:

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 `SENT` or `UNPAID`.
`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: Sets the `notify_merchant` and `notify_customer` query parameters to `false` when he or she sends the invoice. Selects Share link myself from the Send menu when he or she sends the invoice through the web UI Create Invoice page.
`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 `Unpaid (sent)`.
`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 `SENT`.
`PARTIALLY_PAID`	A customer makes a partial payment for the invoice through one of these methods: A customer makes a disconnected partial payment for the invoice and the merchant manually marks the invoice as paid. A customer makes a connected partial payment for the invoice.
`PAYMENT_PENDING`	A customer pays an invoice but the payment is pending for one of these reasons: The payment is an uncleared eCheck. The merchant must either accept the payment before it clears or deny the payment. PayPal risk is reviewing the payment. Note: Most payments never go into a payment-pending state.
`PAID`	A customer fully pays the invoice through one of these methods: A customer makes a connected full payment for the invoice. A customer makes a connected partial payment for the invoice. Then, the customer makes a disconnected payment, such as a check payment, to pay the balance of the invoice and the merchant manually marks the invoice as fully paid.
`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 `SENT` or `UNPAID` status.
`REFUNDED`	A merchant fully refunds an invoice through one these methods: A merchant makes a connected full refund for the invoice. A merchant makes a connected partial refund for the invoice. Then, the merchant makes a disconnected refund, such as a check payment, for the invoice balance and manually marks the invoice as fully refunded.
`PARTIALLY_REFUNDED`	A merchant partially refunds an invoice through one or both of these methods: A merchant makes a disconnected partial refund, such as a check payment, for the invoice and marks the invoice as partially refunded. To complete this action, the merchant must previously mark the invoice as paid. A merchant makes a connected partial refund for a connected partial payment.
`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_infoobject<merchant-info>Required

The merchant information, such as business name, email, address, and so on.

merchant-info properties

10 properties

addressobject<address>Optional

The merchant's address.

billing_infoobject<billing-info>[]Optional

An array of billing information for the invoice recipient.

Note: This value is an array with only one element.

Items1 <= length <= 1

billing-info properties

8 properties

addressobject<address>Optional

The invoice recipient's billing address.

languageenumOptional

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.

shipping_infoobject<shipping-info>Optional

The shipping information for the recipient of the invoice.

shipping-info properties

4 properties

addressobject<address>Optional

The shipping address.

itemsobject<invoice-item>[]Optional

An array of invoice line item information.

Items0 <= length <= 100

invoice-item properties

8 properties

descriptionstringOptional

The item description.

Length0 <= length <= 1000

unit_priceobject<currency>Required

The currency and amount of the item unit price. Value is from `-1000000` to `1000000`. Supports up to two decimal places.

taxobject<tax>Optional

The tax information.

discountobject<discount>Optional

The item discount, as a percent or an amount value.

payment_termobject<payment-term>Optional

The payment due date of the invoice. If you include `due_date`, the `term_type` value is ignored.

discountobject<discount>Optional

The invoice level discount, as a percent or an amount value.

shipping_costobject<shipping-cost>Optional

The shipping amount, as a percent or an amount value.

customobject<custom-amount>Optional

The custom amount to apply to an invoice. If you include a label, you must include a custom amount.

minimum_amount_dueobject<currency>Optional

The minimum amount allowed for a partial payment. Valid only if `allow_partial_payment` is `true`.

total_amountobject<currency>Optional

The total amount of the invoice.

paymentsobject<payment-detail>[]Optional

An array of payment details for the invoice.

Items0 <= length <= 1

refundsobject<refund-detail>[]Optional

An array of refund details for the invoice.

Items0 <= length <= 1

metadataobject<metadata>Optional

The audit information for the invoice.

paid_amountobject<payment-summary>Optional

The payment summary of the invoice. Includes the amount paid through PayPal and other sources.

refunded_amountobject<payment-summary>Optional

The payment summary of the invoice. Includes the amount refunded through PayPal and other sources.

On this page

If you accept cookies, we'll use them to improve and customise your experience and enable our partners to show you personalised PayPal ads when you visit other sites. Manage cookies and learn more

invoice_list

merchant-info properties

address properties

phone properties

phone properties

billing-info properties

phone properties

address properties

shipping-info properties

address properties

participant properties

invoice-item properties

currency properties

tax properties

currency properties

discount properties

currency properties

payment-term properties

discount properties

currency properties

shipping-cost properties

currency properties

tax properties

currency properties

custom-amount properties

currency properties

currency properties

currency properties

payment-detail properties

currency properties

refund-detail properties

currency properties

metadata properties

payment-summary properties

currency properties

currency properties

payment-summary properties

currency properties

currency properties

file-attachment properties

link_description properties

link_schema properties

media properties

link_schema properties

media properties

Back to top

On this page