Search for invoices

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

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

For Reading the invoice details.https://uri.paypal.com/services/invoicing/invoices/read

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

recipient_emailstringOptional

Filters the search by the email address.

Match^[\S\s]*$Length0 <= length <= 254

recipient_first_namestringOptional

Filters the search by the recipient first name.

Match^[\S\s]*$Length0 <= length <= 140

recipient_last_namestringOptional

Filters the search by the recipient last name.

Match^[\S\s]*$Length0 <= length <= 140

recipient_business_namestringOptional

Filters the search by the recipient business name.

Match^[\S\s]*$Length0 <= length <= 300

invoice_numberstringOptional

Filters the search by the invoice number.

Match^[\S\s]*$Length0 <= length <= 25

statusarray<invoice_status>Optional

An array of status values.

Items0 <= length <= 5

referencestringOptional

The reference data. Includes a Purchase Order (PO) number.

Match^[\S\s]*$Length0 <= length <= 120

currency_codestring<currency_code>Optional

The [3-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.

Match^[\S\s]*$Length3 <= length <= 3

memostringOptional

A private bookkeeping memo for the user.

Match^[\S\s]*$Length0 <= length <= 500

total_amount_rangeobject<amount_range>Optional

The amount range.

invoice_date_rangeobject<date_range>Optional

The date range. Filters invoices by creation date, invoice date, due date, and payment date.

due_date_rangeobject<date_range>Optional

The date range. Filters invoices by creation date, invoice date, due date, and payment date.

payment_date_rangeobject<date_time_range>Optional

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

creation_date_rangeobject<date_time_range>Optional

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

archivedbooleanOptional

Indicates whether to list merchant-archived invoices in the response. Value is:

true. Response lists only merchant-archived invoices.
false. Response lists only unarchived invoices.
null. Response lists all invoices.

fieldsarray<field>Optional

A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are items, payments, refunds, additional_recipients_info, and attachments.

Items0 <= length <= 5

Response Body

`application/json`

curl -X POST "https://example.com/v2/invoicing/search-invoices?page=1&page_size=1&total_required=true" \  -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \  -H "Content-Type: application/json" \  -d '{    "total_amount_range": {      "lower_amount": {        "currency_code": "USD",        "value": "50.00"      },      "upper_amount": {        "currency_code": "USD",        "value": "50.00"      }    },    "invoice_date_range": {      "start": "2018-06-01",      "end": "2018-06-21"    }  }'

{  "total_items": 6,  "total_pages": 1,  "items": [    {      "id": "INV2-Z56S-5LLA-Q52L-CPZ5",      "status": "DRAFT",      "detail": {        "invoice_number": "#123",        "reference": "deal-ref",        "invoice_date": "2018-11-12",        "currency_code": "USD",        "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"        },        "metadata": {          "create_time": "2018-11-12T08:00:20Z",          "recipient_view_url": "https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5",          "invoicer_view_url": "https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5"        }      },      "invoicer": {        "email_address": "merchant@example.com"      },      "primary_recipients": [        {          "billing_info": {            "email_address": "bill-me@example.com"          }        }      ],      "amount": {        "currency_code": "USD",        "value": "74.21"      },      "links": [        {          "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5",          "rel": "self",          "method": "GET"        }      ]    }  ],  "links": [    {      "href": "https://api-m.paypal.com/v2/invoicing/invoices?page=2&page_size=10&total_required=true",      "rel": "next",      "method": "POST"    }  ]}

Query Parameters

Header Parameters

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

recipient_emailstringOptional

Filters the search by the email address.

Match^[\S\s]*$Length0 <= length <= 254

recipient_first_namestringOptional

Filters the search by the recipient first name.

Match^[\S\s]*$Length0 <= length <= 140

recipient_last_namestringOptional

Filters the search by the recipient last name.

Match^[\S\s]*$Length0 <= length <= 140

recipient_business_namestringOptional

Filters the search by the recipient business name.

Match^[\S\s]*$Length0 <= length <= 300

invoice_numberstringOptional

Filters the search by the invoice number.

Match^[\S\s]*$Length0 <= length <= 25

statusarray<invoice_status>Optional

An array of status values.

Items0 <= length <= 5

referencestringOptional

The reference data. Includes a Purchase Order (PO) number.

Match^[\S\s]*$Length0 <= length <= 120

currency_codestring<currency_code>Optional

The [3-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency.

Match^[\S\s]*$Length3 <= length <= 3

memostringOptional

A private bookkeeping memo for the user.

Match^[\S\s]*$Length0 <= length <= 500

total_amount_rangeobject<amount_range>Optional

The amount range.

invoice_date_rangeobject<date_range>Optional

The date range. Filters invoices by creation date, invoice date, due date, and payment date.

due_date_rangeobject<date_range>Optional

The date range. Filters invoices by creation date, invoice date, due date, and payment date.

payment_date_rangeobject<date_time_range>Optional

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

creation_date_rangeobject<date_time_range>Optional

The date and time range. Filters invoices by creation date, invoice date, due date, and payment date.

archivedbooleanOptional

Indicates whether to list merchant-archived invoices in the response. Value is:

true. Response lists only merchant-archived invoices.
false. Response lists only unarchived invoices.
null. Response lists all invoices.

fieldsarray<field>Optional

Items0 <= length <= 5

curl -X POST "https://example.com/v2/invoicing/search-invoices?page=1&page_size=1&total_required=true" \ -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \ -H "Content-Type: application/json" \ -d '{ "total_amount_range": { "lower_amount": { "currency_code": "USD", "value": "50.00" }, "upper_amount": { "currency_code": "USD", "value": "50.00" } }, "invoice_date_range": { "start": "2018-06-01", "end": "2018-06-21" } }'

{ "total_items": 6, "total_pages": 1, "items": [ { "id": "INV2-Z56S-5LLA-Q52L-CPZ5", "status": "DRAFT", "detail": { "invoice_number": "#123", "reference": "deal-ref", "invoice_date": "2018-11-12", "currency_code": "USD", "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" }, "metadata": { "create_time": "2018-11-12T08:00:20Z", "recipient_view_url": "https://www.api-m.paypal.com/invoice/p#Z56S5LLAQ52LCPZ5", "invoicer_view_url": "https://www.api-m.paypal.com/invoice/details/INV2-Z56S-5LLA-Q52L-CPZ5" } }, "invoicer": { "email_address": "merchant@example.com" }, "primary_recipients": [ { "billing_info": { "email_address": "bill-me@example.com" } } ], "amount": { "currency_code": "USD", "value": "74.21" }, "links": [ { "href": "https://api-m.paypal.com/v2/invoicing/invoices/INV2-Z56S-5LLA-Q52L-CPZ5", "rel": "self", "method": "GET" } ] } ], "links": [ { "href": "https://api-m.paypal.com/v2/invoicing/invoices?page=2&page_size=10&total_required=true", "rel": "next", "method": "POST" } ]}

amount_range properties

money properties

money properties

date_range properties

date_range properties

date_time_range properties

date_time_range properties

200application/json

400application/json

401application/json

403application/json

500application/json

defaultapplication/json

On this page

On this page

On this page

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

Search for invoices

amount_range properties

money properties

money properties

date_range properties

date_range properties

date_time_range properties

date_time_range properties

200application/json

400application/json

401application/json

403application/json

500application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`