Invoices (2)

API Version v2

Use the Invoicing API to create, send, and manage invoices. You can also use the API or webhooks to track invoice payments. When you send an invoice to a customer, the invoice moves from draft to payable state. PayPal then emails the customer a link to the invoice on the PayPal website. Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card. For more information, see the Invoicing Overview and the Invoicing Integration Guide.

Create draft invoice

post/v2/invoicing/invoices

Creates a draft invoice. To move the invoice from a draft to payable state, you must send the invoice.

In the JSON request body, include invoice details including merchant information. The invoice object must include an items array.

Note: The merchant that you specify in an invoice must have a PayPal account in good standing.
.

SecurityOauth2
Request
Request Body schema: application/json

The invoice details which includes all information of the invoice like items, billing information.

Array of objects (recipient_info) <= 100 items

The billing and shipping information. Includes name, email, address, phone and language.

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) <= 100 items

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Array of objects (item) <= 100 items

An array of invoice line item information.

required
object (invoice_detail)

The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.

object (invoicer_info)

The invoicer business information that appears on the invoice.

object (configuration)

The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

object (amount_summary_detail)

The invoice amount summary of item total, discount, tax total, and shipping.

object (payments)

An array of payments registered against the invoice.

object (refunds)

The invoicing refund details. Includes the refund type, date, amount, and method.

Responses
200

OK

Request samples
application/json
{
  • "detail": {
    • "currency_code": "USD",
    • "invoice_number": "#123",
    • "reference": "deal-ref",
    • "invoice_date": "2018-11-12",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      }
    },
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "www.test.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy- Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25"
        },
      • "discount": {
        • "percent": "5"
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga t-shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25"
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "breakdown": {
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25"
          }
        },
      • "discount": {
        • "invoice_discount": {
          • "percent": "5"
          }
        }
      }
    }
}
Response samples
application/json
{
  • "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
  • "status": "DRAFT",
  • "detail": {},
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "https://example.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga T Shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    },
  • "due_amount": {
    • "currency_code": "USD",
    • "value": "74.21"
    },
  • "links": []
}

List invoices

get/v2/invoicing/invoices

Lists invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.

SecurityOauth2
Request
query Parameters
page
integer [ 1 .. 1000 ]
Default: 1

The page number to be retrieved, for the list of items. So, a combination of page=1 and page_size=20 returns the first 20 invoices. A combination of page=2 and page_size=20 returns the next 20 invoices.

page_size
integer [ 1 .. 100 ]
Default: 20

The maximum number of invoices to return in the response.

total_required
boolean
Default: false

Indicates whether the to show total_pages and total_items in the response.

fields
string

A comma-separated list of additional fields to return, if available.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices with details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices?total_required=true \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
Response samples
{}

Send invoice

post/v2/invoicing/invoices/{invoice_id}/send

Sends or schedules an invoice, by ID, to be sent to a customer. The action depends on the invoice issue date:

  • If the invoice issue date is current or in the past, sends the invoice immediately.
  • If the invoice issue date is in the future, schedules the invoice to be sent on that date.
To suppress the merchant's email notification, set the send_to_invoicer body parameter to false. To send the invoice through a share link and not through PayPal, set the send_to_recipient parameter to false in the notification object. The send_to_recipient parameter does not apply to a future issue date because the invoice is scheduled to be sent through PayPal on that date.
Notes:
  • After you send an invoice, resending it has no effect.
  • To send a notification for updates, update the invoice and set the send_to_recipient body parameter to true.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to send.

Request Body schema: application/json

The email or SMS notification to send to the payer when they send an invoice..

subject
string <= 4000 characters

The subject of the email that is sent as a notification to the recipient.

note
string <= 4000 characters

A note to the payer.

send_to_invoicer
boolean
Default: false

Indicates whether to send a copy of the email to the merchant.

send_to_recipient
boolean
Default: true

Indicates whether to send a copy of the email to the recipient.

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) <= 100 items

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Responses
202

A successful request returns the HTTP 202 Accepted status code with no JSON response body, when the invoice issue date is in future.

Request samples
application/json
{
  • "send_to_invoicer": true
}
Response samples
{
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}

Send invoice reminder

post/v2/invoicing/invoices/{invoice_id}/remind

Sends a reminder to the payer about an invoice, by ID. In the JSON request body, include a notification object that defines the subject of the reminder and other details.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice for which to send a reminder.

Request Body schema: application/json

The email or SMS notification that will be sent to the payer for reminder.

subject
string <= 4000 characters

The subject of the email that is sent as a notification to the recipient.

note
string <= 4000 characters

A note to the payer.

send_to_invoicer
boolean
Default: false

Indicates whether to send a copy of the email to the merchant.

send_to_recipient
boolean
Default: true

Indicates whether to send a copy of the email to the recipient.

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) <= 100 items

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
{
  • "subject": "Reminder: Payment due for the invoice #ABC-123",
  • "note": "Please pay before the due date to avoid incurring late payment charges which will be adjusted in the next bill generated.",
  • "send_to_invoicer": true,
  • "additional_recipients": [
    • "customer-a@example.com",
    • "customer@example.com"
    ]
}

Cancel sent invoice

post/v2/invoicing/invoices/{invoice_id}/cancel

Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to cancel.

Request Body schema: application/json

The email or SMS notification that will be sent to the payer on cancellation.

subject
string <= 4000 characters

The subject of the email that is sent as a notification to the recipient.

note
string <= 4000 characters

A note to the payer.

send_to_invoicer
boolean
Default: false

Indicates whether to send a copy of the email to the merchant.

send_to_recipient
boolean
Default: true

Indicates whether to send a copy of the email to the recipient.

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) <= 100 items

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples
application/json
{
  • "subject": "Invoice Cancelled",
  • "note": "Cancelling the invoice",
  • "send_to_invoicer": true,
  • "send_to_recipient": true,
  • "additional_recipients": [
    • "user@example.com"
    ]
}

Record payment for invoice

post/v2/invoicing/invoices/{invoice_id}/payments

Records a payment for the invoice. If no payment is due, the invoice is marked as PAID. Otherwise, the invoice is marked as PARTIALLY PAID.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to mark as paid.

Request Body schema: application/json

The details of the payment to record against the invoice.

payment_id
string <= 22 characters

The ID for a PayPal payment transaction. Required for the PAYPAL payment type.

note
string <= 2000 characters

A note associated with an external cash or check payment.

payment_date
string <ppaas_date_notime_v2> (date_no_time) = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

method
required
string (payment_method)

The payment mode or method through which the invoicer can accept the payment.

Enum: Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

object (contact_information)

The contact information of the user. Includes name and address.

Responses
200

A successful request returns the HTTP 200 Created status code and a reference to the recorded payment.

Request samples
application/json
{
  • "method": "BANK_TRANSFER",
  • "payment_date": "2018-05-01",
  • "amount": {
    • "currency_code": "USD",
    • "value": "10.00"
    }
}
Response samples
{
  • "payment_id": "EXTR-86F38350LX4353815"
}

Delete external payment

delete/v2/invoicing/invoices/{invoice_id}/payments/{transaction_id}

Deletes an external payment, by invoice ID and transaction ID.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice from which to delete an external payment transaction.

transaction_id
required
string

The ID of the external payment transaction to delete.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5/payments/EXTR-86F38350LX4353815 \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0'

Record refund for invoice

post/v2/invoicing/invoices/{invoice_id}/refunds

Records a refund for the invoice. If all payments are refunded, the invoice is marked as REFUNDED. Otherwise, the invoice is marked as PARTIALLY REFUNDED.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to mark as refunded.

Request Body schema: application/json

The details of the refund to record against the invoice.

refund_date
string <ppaas_date_notime_v2> (date_no_time) = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.

object (Money)

The currency and amount for a financial transaction, such as a balance or payment due.

method
required
string (payment_method)

The payment mode or method through which the invoicer can accept the payments.

Enum: Description
BANK_TRANSFER

Payments can be received through bank transfers.

CASH

Payments can be received as cash.

CHECK

Payments can be received as check.

CREDIT_CARD

Payments can be received through credit card payments.

DEBIT_CARD

Payments can be received through debit card payments.

PAYPAL

Payments can be received through paypal payments.

WIRE_TRANSFER

Payments can be received through wire transfer.

OTHER

Payments can be received through other modes.

Responses
200

A successful request returns the HTTP 200 Created status code and a reference to the recorded refund.

Request samples
application/json
{
  • "method": "BANK_TRANSFER",
  • "refund_date": "2018-05-21",
  • "amount": {
    • "currency_code": "USD",
    • "value": "5.00"
    }
}
Response samples
{
  • "refund_id": "EXTR-2LG703375E477444T"
}

Delete external refund

delete/v2/invoicing/invoices/{invoice_id}/refunds/{transaction_id}

Deletes an external refund, by invoice ID and transaction ID.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice from which to delete the external refund transaction.

transaction_id
required
string

The ID of the external refund transaction to delete.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-333R-YUQL-YNNN-D7WF/refunds/EXTR-2LG703375E477444T \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0'

Generate QR code

post/v2/invoicing/invoices/{invoice_id}/generate-qr-code

Generates a QR code for an invoice, by ID. The QR code is a PNG image in Base64-encoded format that corresponds to the invoice ID. You can generate a QR code for an invoice and add it to a paper or PDF invoice. When customers use their mobile devices to scan the QR code, they are redirected to the PayPal mobile payment flow where they can view the invoice and pay online with PayPal or a credit card. Before you get a QR code, you must create an invoice and send an invoice to move the invoice from a draft to payable state. Do not include an email address if you do not want the invoice emailed.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice for which to generate a QR code.

Request Body schema: application/json

Optional configuration parameters to adjust QR code width, height and the encoded URL.

width
integer [ 150 .. 500 ]
Default: 500

The width, in pixels, of the QR code image. Value is from 150 to 500.

height
integer [ 150 .. 500 ]
Default: 500

The height, in pixels, of the QR code image. Value is from 150 to 500.

action
string <= 7 characters (?i)^(pay|details)$
Default: "pay"

The type of URL for which to generate a QR code. Valid values are pay and details.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the QR code as a PNG image.

Request samples
application/json
{
  • "width": 400,
  • "height": 400
}
Response samples
application/json
"--95dbdbed-7536-4c24-b5ca-bcdbc0006612 Content-Disposition: form-data; name=\"image\" Content-Type: application/octet-stream iVBORw0KGgoAAAANSUhEUgAAAJYAAACWAQAAAAAUekxPAAABxUlEQVR42u2WMY7kIBBFq0VA1n0BS1yDjCvZF7DxBdxXIuMaSFzAzgiQaz6t9mxLm1AbrCYYy4H1AlT1f9XHxH89lX7Z/2KJKN3CMIW6FCInYplLPtisoU6FTyHzti6RN5tPm+5ixrtTp0uP8g8s744eMS1yxvikNEOJz966GPTLaOL1fmjaxfAkaLCy2t2Hl10sPUIaNY1araFhCat3TbODDPkZ68Ii1sqfX62c1rzP62W8uWG0aiMaxSyvpS4hez2MzXkZg+FL4NNCwku/XtZ8g/Be550+Pe9jWj0x41rt1ngZyxzYa+NpmDjNMlYx1yhhs2glM8vY3IQ3qGWz9Tqvk7F3cGyYNd3KQDKGSWFGDjFNIZ8yhuWgR8gb5jR8+9bJ8rPUCd3oYbY4VcQqaWSYWRGcdnhnSS+D6lhKJIE5+JrTXtaquDtzuuypXrV0stRKwLAUzFodnYjxERP28ihtLw8WsbQE7JbxCD9SmxMxfsUYpiZ7lxYWMewltzuqKMz4n13tYi3vl6jW2FJQynBH+Za7Zie6sZRhNVXLTkqTmGUE5xSRu5dv3Qz3uYdj0bwkFLGWfxxoJMXx28tO9vu/9oPYF0bR/hBeOiwMAAAAAElFTkSuQmCC --95dbdbed-7536-4c24-b5ca-bcdbc0006612--"

Generate invoice number

post/v2/invoicing/generate-next-invoice-number

Generates the next invoice number that is available to the merchant. The next invoice number uses the prefix and suffix from the last invoice number and increments the number by one. For example, the next invoice number after INVOICE-1234 is INVOICE-1235.

SecurityOauth2
Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the next invoice number.

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/generate-next-invoice-number \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
Response samples
application/json
{
  • "invoice_number": "ee0044"
}

Show invoice details

get/v2/invoicing/invoices/{invoice_id}

Shows details for an invoice, by ID.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice for which to show details.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details.

Request samples 
curl -v -X GET https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0' \
-H 'Content-Type: application/json'
Response samples
application/json
{
  • "id": "INV2-Z56S-5LLA-Q52L-CPZ5",
  • "status": "DRAFT",
  • "detail": {},
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "https://example.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga T Shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    },
  • "due_amount": {
    • "currency_code": "USD",
    • "value": "74.21"
    },
  • "links": []
}

Fully update invoice

put/v2/invoicing/invoices/{invoice_id}

Fully updates an invoice, by ID. In the JSON request body, include a complete invoice object. This call does not support partial updates.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the invoice to update.

query Parameters
send_to_recipient
boolean
Default: true

Indicates whether to send the invoice update notification to the recipient.

send_to_invoicer
boolean
Default: true

Indicates whether to send the invoice update notification to the merchant.

Request Body schema: application/json

A representation of changes to make in the invoice.

Array of objects (recipient_info) <= 100 items

The billing and shipping information. Includes name, email, address, phone and language.

additional_recipients
Array of strings <ppaas_common_email_address_v2> (email_address) <= 100 items

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Array of objects (item) <= 100 items

An array of invoice line item information.

required
object (invoice_detail)

The details of the invoice. Includes invoice number, date, payment terms, and audit metadata.

object (invoicer_info)

The invoicer business information that appears on the invoice.

object (configuration)

The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

object (amount_summary_detail)

The invoice amount summary of item total, discount, tax total, and shipping.

object (payments)

An array of payments registered against the invoice.

object (refunds)

The invoicing refund details. Includes the refund type, date, amount, and method.

Responses
200

A successful request returns the HTTP 200 OK status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation.

Request samples
application/json
{
  • "detail": {
    • "currency_code": "USD",
    • "invoice_number": "#123",
    • "reference": "deal-refernce-update",
    • "invoice_date": "2018-11-12",
    • "note": "Thank you for your business.",
    • "term": "No refunds after 30 days.",
    • "memo": "This is a long contract",
    • "payment_term": {
      • "term_type": "NET_10",
      • "due_date": "2018-11-22"
      }
    },
  • "id": "INV2-C82X-JNN9-Y6S5-CNXW",
  • "status": "DRAFT",
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "www.test.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga t-shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    }
}
Response samples
{
  • "id": "INV2-C82X-JNN9-Y6S5-CNXW",
  • "status": "DRAFT",
  • "detail": {},
  • "invoicer": {
    • "name": {
      • "given_name": "David",
      • "surname": "Larusso"
      },
    • "address": {
      • "address_line_1": "1234 First Street",
      • "address_line_2": "337673 Hillside Court",
      • "admin_area_2": "Anytown",
      • "admin_area_1": "CA",
      • "postal_code": "98765",
      • "country_code": "US"
      },
    • "email_address": "merchant@example.com",
    • "phones": [
      • {
        • "country_code": "001",
        • "national_number": "4085551234",
        • "phone_type": "MOBILE"
        }
      ],
    • "website": "https://example.com",
    • "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
    • "logo_url": "https://example.com/logo.PNG",
    • "additional_notes": "2-4"
    },
  • "primary_recipients": [
    • {
      • "billing_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          },
        • "email_address": "bill-me@example.com",
        • "phones": [
          • {
            • "country_code": "001",
            • "national_number": "4884551234",
            • "phone_type": "HOME"
            }
          ],
        • "additional_info_value": "add-info"
        },
      • "shipping_info": {
        • "name": {
          • "given_name": "Stephanie",
          • "surname": "Meyers"
          },
        • "address": {
          • "address_line_1": "1234 Main Street",
          • "admin_area_2": "Anytown",
          • "admin_area_1": "CA",
          • "postal_code": "98765",
          • "country_code": "US"
          }
        }
      }
    ],
  • "items": [
    • {
      • "name": "Yoga Mat",
      • "description": "Elastic mat to practice yoga.",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "50.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "3.27"
          }
        },
      • "discount": {
        • "percent": "5",
        • "amount": {
          • "currency_code": "USD",
          • "value": "2.5"
          }
        },
      • "unit_of_measure": "QUANTITY"
      },
    • {
      • "name": "Yoga t-shirt",
      • "quantity": "1",
      • "unit_amount": {
        • "currency_code": "USD",
        • "value": "10.00"
        },
      • "tax": {
        • "name": "Sales Tax",
        • "percent": "7.25",
        • "amount": {
          • "currency_code": "USD",
          • "value": "0.34"
          }
        },
      • "discount": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "5.00"
          }
        },
      • "unit_of_measure": "QUANTITY"
      }
    ],
  • "configuration": {
    • "partial_payment": {
      • "allow_partial_payment": true,
      • "minimum_amount_due": {
        • "currency_code": "USD",
        • "value": "20.00"
        }
      },
    • "allow_tip": true,
    • "tax_calculated_after_discount": true,
    • "tax_inclusive": false,
    • "template_id": "TEMP-19V05281TU309413B"
    },
  • "amount": {
    • "currency_code": "USD",
    • "value": "74.21",
    • "breakdown": {
      • "item_total": {
        • "currency_code": "USD",
        • "value": "60.00"
        },
      • "custom": {
        • "label": "Packing Charges",
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          }
        },
      • "shipping": {
        • "amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "tax": {
          • "name": "Sales Tax",
          • "percent": "7.25",
          • "amount": {
            • "currency_code": "USD",
            • "value": "0.73"
            }
          }
        },
      • "discount": {
        • "item_discount": {
          • "currency_code": "USD",
          • "value": "-7.50"
          },
        • "invoice_discount": {
          • "percent": "5",
          • "amount": {
            • "currency_code": "USD",
            • "value": "-2.63"
            }
          }
        },
      • "tax_total": {
        • "currency_code": "USD",
        • "value": "4.34"
        }
      }
    },
  • "due_amount": {
    • "currency_code": "USD",
    • "value": "74.21"
    },
  • "links": []
}

Delete invoice

delete/v2/invoicing/invoices/{invoice_id}

Deletes a draft or scheduled invoice, by ID. Deletes invoices in the draft or scheduled state only. For invoices that have already been sent, you can cancel the invoice. After you delete a draft or scheduled invoice, you can no longer use it or show its details. However, you can reuse its invoice number.

SecurityOauth2
Request
path Parameters
invoice_id
required
string

The ID of the draft invoice to delete.

Responses
204

A successful request returns the HTTP 204 No Content status code with no JSON response body.

Request samples 
curl -v -X DELETE https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5 \
-H 'Authorization: Bearer zekwhYgsYYI0zDg0p_Nf5v78VelCfYR0'

Search for invoices

post/v2/invoicing/search-invoices

Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.

Security