Invoicing / Reference / Invoice Lifecycle

Invoice Lifecycle


PayPal tracks both the lifecycle status and the payment or refund status of an invoice.

An invoice payment can be either:

  • Connected to an invoice. To make a payment, the customer clicks Pay on the invoice and 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 until it has a status of SENT or UNPAID.
UNPAID

A merchant sends the invoice and chooses to suppress the PayPal email notification.

After the merchant sends the invoice with this option, the invoice has the UNPAID status rather than the DRAFT status.

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 through the API.

  • 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 uses the API or the Create Invoice page to send the invoice with the default PayPal email notification.

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 the invoice to send the invoice on a future date.

On that date at 07:00 in the preferred time zone of the merchant's PayPal account profile, PayPal:

  1. Emails an invoice notification to the merchant and the customer.
  2. Adds an online payment button to the customer’s view of the invoice.
  3. Updates the invoice status to SENT.
PARTIALLY_PAID

A customer makes a partial payment for the invoice.

To make a partial payment for the invoice, the customer makes either:

  • A disconnected partial payment for the invoice. Then, the merchant manually marks the invoice as paid.

  • 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.

To fully pay the invoice, the customer makes either:

  • A connected full payment for the invoice.

  • A connected partial payment for the invoice. Then, to pay the balance of the invoice, the customer makes a disconnected payment, such as a check payment. Then, the merchant manually marks the invoice as fully paid.
MARKED_AS_PAID

A customer makes a disconnected payment for the balance of the invoice. Then, the merchant manually marks the invoice as paid.
CANCELLED

A merchant or customer cancels a sent invoice with either SENT or UNPAID status.
REFUNDED

A merchant fully refunds the invoice.

To fully refund an invoice, the merchant makes either:

  • A connected full refund for the invoice.

  • 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.

To partially refund the invoice, the merchant makes either or both:

  • 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 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.