Search for invoices
POST {{base_url}}/v2/invoicing/search-invoices?page=1&page_size=10&total_required=true
Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria.
Request Params
| Key | Datatype | Required | Description |
|---|---|---|---|
page | number | 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 | number | The page size for the search results. | |
total_required | boolean | Indicates whether the to show <code>total_pages</code> and <code>total_items</code> in the response. |
Request Body
{"recipient_email"=>"foobuyer@gmail.com", "recipient_first_name"=>"Stephanie", "recipient_last_name"=>"Meyers", "recipient_business_name"=>"", "invoice_number"=>"1644275305", "status"=>["DRAFT"], "reference"=>"298", "currency_code"=>"USD", "memo"=>"<A private bookkeeping note for merchant.>", "total_amount_range"=>{"lower_amount"=>{"currency_code"=>"USD", "value"=>"100.00"}, "upper_amount"=>{"currency_code"=>"USD", "value"=>"1000.00"}}, "invoice_date_range"=>{"start"=>"2022-01-01", "end"=>"2022-02-07"}}
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Content-Type | string | The Content-Type header field is used to specify the nature of the data in the body of an entity. PayPal REST APIs support application/json. | |
PayPal-Request-Id | string | The server stores keys for 6 hours. The API callers can request the times to up to 72 hours by speaking to their Account Manager. | |
PayPal-Client-Metadata-Id | string | Optional. Verifies that the payment originates from a valid, user-consented device and application. Reduces fraud and decreases declines. Transactions that do not include a client metadata ID are not eligible for PayPal Seller Protection. | |
PayPal-Partner-Attribution-Id | string | Optional. Identifies the caller as a PayPal partner. To receive revenue attribution, specify a unique build notation (BN) code. BN codes provide tracking on all transactions that originate or are associated with a particular partner. To find your BN code, see Code and Credential Reference. | |
PayPal-Auth-Assertion | string | An API client-provided JSON Web Token (JWT) assertion that identifies the merchant. To use this header, you must get consent to act on behalf of a merchant. | |
Prefer | string | The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul> | |
Prefer | string | The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul> |
RESPONSES
status: OK
{"total_pages":7,"total_items":69,"items":[{"id":"INV2-WP4T-WWHH-8KD5-HEFC","status":"DRAFT","detail":{"reference":"298","currency_code":"USD","note":"\u003cA note to the invoice recipient. Also appears on the invoice notification email.\u003e","memo":"\u003cA private bookkeeping note for merchant.\u003e","invoice_number":"1644275305","invoice_date":"2022-01-04","payment_term":{"due_date":"2022-01-14"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T23:08:26Z"}},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"198.21"},"due_amount":{"currency_code":"USD","value":"198.21"},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-WP4T-WWHH-8KD5-HEFC","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-WP4T-WWHH-8KD5-HEFC/send","rel":"send","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-WP4T-WWHH-8KD5-HEFC","rel":"replace","method":"PUT"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-WP4T-WWHH-8KD5-HEFC","rel":"delete","method":"DELETE"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-WP4T-WWHH-8KD5-HEFC/payments","rel":"record-payment","method":"POST"}]},{"id":"INV2-7J3Z-98HC-VVGU-PF6Z","status":"PARTIALLY_PAID","detail":{"reference":"deal-refernce-update","currency_code":"USD","note":"Thank you for your business.","memo":"This is a long contract","invoice_number":"1644274671","invoice_date":"2018-11-12","payment_term":{"due_date":"2018-11-22"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:57:27Z"}},"invoicer":{"email_address":"merchant@example.com"},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"74.21"},"due_amount":{"currency_code":"USD","value":"44.21"},"payments":{"paid_amount":{"currency_code":"USD","value":"30.00"}},"refunds":{"refund_amount":{"currency_code":"USD","value":"5.00"}},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-7J3Z-98HC-VVGU-PF6Z","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-7J3Z-98HC-VVGU-PF6Z/payments","rel":"record-payment","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-7J3Z-98HC-VVGU-PF6Z/refunds","rel":"record-refund","method":"POST"}]},{"id":"INV2-NBQS-HPVR-4BGH-H9KP","status":"PARTIALLY_PAID","detail":{"reference":"deal-refernce-update","currency_code":"USD","note":"Thank you for your business.","memo":"This is a long contract","invoice_number":"1644274592","invoice_date":"2018-11-12","payment_term":{"due_date":"2018-11-22"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:56:02Z"}},"invoicer":{"email_address":"merchant@example.com"},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"74.21"},"due_amount":{"currency_code":"USD","value":"44.21"},"payments":{"paid_amount":{"currency_code":"USD","value":"30.00"}},"refunds":{"refund_amount":{"currency_code":"USD","value":"5.00"}},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-NBQS-HPVR-4BGH-H9KP","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-NBQS-HPVR-4BGH-H9KP/payments","rel":"record-payment","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-NBQS-HPVR-4BGH-H9KP/refunds","rel":"record-refund","method":"POST"}]},{"id":"INV2-56LB-WK75-3DX2-J43P","status":"DRAFT","detail":{"reference":"deal-refernce-update","currency_code":"USD","note":"Thank you for your business.","memo":"This is a long contract","invoice_number":"1644274492","invoice_date":"2018-11-12","payment_term":{"due_date":"2018-11-22"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:54:37Z"}},"invoicer":{"email_address":"merchant@example.com"},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"74.21"},"due_amount":{"currency_code":"USD","value":"74.21"},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-56LB-WK75-3DX2-J43P","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-56LB-WK75-3DX2-J43P/send","rel":"send","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-56LB-WK75-3DX2-J43P","rel":"replace","method":"PUT"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-56LB-WK75-3DX2-J43P","rel":"delete","method":"DELETE"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-56LB-WK75-3DX2-J43P/payments","rel":"record-payment","method":"POST"}]},{"id":"INV2-U95S-EB3F-W2WE-DMRN","status":"PARTIALLY_PAID","detail":{"reference":"deal-refernce-update","currency_code":"USD","note":"Thank you for your business.","memo":"This is a long contract","invoice_number":"1644274445","invoice_date":"2018-11-12","payment_term":{"due_date":"2018-11-22"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:49:17Z"}},"invoicer":{"email_address":"merchant@example.com"},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"74.21"},"due_amount":{"currency_code":"USD","value":"64.21"},"payments":{"paid_amount":{"currency_code":"USD","value":"10.00"}},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-U95S-EB3F-W2WE-DMRN","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-U95S-EB3F-W2WE-DMRN/payments","rel":"record-payment","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-U95S-EB3F-W2WE-DMRN/refunds","rel":"record-refund","method":"POST"}]},{"id":"INV2-6GCT-RGT9-JXGA-TZAE","status":"PARTIALLY_PAID","detail":{"reference":"\u003cThe reference data. Includes a post office (PO) number.\u003e","currency_code":"USD","note":"\u003cA note to the invoice recipient. Also appears on the invoice notification email.\u003e","memo":"\u003cA private bookkeeping note for merchant.\u003e","invoice_number":"1644273964","invoice_date":"2022-01-04","payment_term":{"due_date":"2022-01-14"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:46:04Z"}},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"198.21"},"due_amount":{"currency_code":"USD","value":"188.21"},"payments":{"paid_amount":{"currency_code":"USD","value":"10.00"}},"refunds":{"refund_amount":{"currency_code":"USD","value":"5.00"}},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-6GCT-RGT9-JXGA-TZAE","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-6GCT-RGT9-JXGA-TZAE/payments","rel":"record-payment","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-6GCT-RGT9-JXGA-TZAE/refunds","rel":"record-refund","method":"POST"}]},{"id":"INV2-8B9B-RB25-PBKA-2LEZ","status":"REFUNDED","detail":{"reference":"\u003cThe reference data. Includes a post office (PO) number.\u003e","currency_code":"USD","note":"\u003cA note to the invoice recipient. Also appears on the invoice notification email.\u003e","memo":"\u003cA private bookkeeping note for merchant.\u003e","invoice_number":"1644273499","invoice_date":"2022-01-04","payment_term":{"due_date":"2022-01-14"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:38:19Z"}},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"198.21"},"due_amount":{"currency_code":"USD","value":"0.00"},"payments":{"paid_amount":{"currency_code":"USD","value":"198.21"}},"refunds":{"refund_amount":{"currency_code":"USD","value":"198.21"}},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-8B9B-RB25-PBKA-2LEZ","rel":"self","method":"GET"}]},{"id":"INV2-YXDK-4FLQ-K2UQ-2BHS","status":"DRAFT","detail":{"reference":"\u003cThe reference data. Includes a post office (PO) number.\u003e","currency_code":"USD","note":"\u003cA note to the invoice recipient. Also appears on the invoice notification email.\u003e","memo":"\u003cA private bookkeeping note for merchant.\u003e","invoice_number":"1644272108","invoice_date":"2022-01-04","payment_term":{"due_date":"2022-01-14"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:15:08Z"}},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"198.21"},"due_amount":{"currency_code":"USD","value":"198.21"},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-YXDK-4FLQ-K2UQ-2BHS","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-YXDK-4FLQ-K2UQ-2BHS/send","rel":"send","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-YXDK-4FLQ-K2UQ-2BHS","rel":"replace","method":"PUT"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-YXDK-4FLQ-K2UQ-2BHS","rel":"delete","method":"DELETE"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-YXDK-4FLQ-K2UQ-2BHS/payments","rel":"record-payment","method":"POST"}]},{"id":"INV2-GJVZ-PTEW-BAHM-QRZX","status":"DRAFT","detail":{"reference":"\u003cThe reference data. Includes a post office (PO) number.\u003e","currency_code":"USD","note":"\u003cA note to the invoice recipient. Also appears on the invoice notification email.\u003e","memo":"\u003cA private bookkeeping note for merchant.\u003e","invoice_number":"1644272025","invoice_date":"2022-01-04","payment_term":{"due_date":"2022-01-14"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:13:45Z"}},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"196.90"},"due_amount":{"currency_code":"USD","value":"196.90"},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-GJVZ-PTEW-BAHM-QRZX","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-GJVZ-PTEW-BAHM-QRZX/send","rel":"send","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-GJVZ-PTEW-BAHM-QRZX","rel":"replace","method":"PUT"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-GJVZ-PTEW-BAHM-QRZX","rel":"delete","method":"DELETE"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-GJVZ-PTEW-BAHM-QRZX/payments","rel":"record-payment","method":"POST"}]},{"id":"INV2-SXKQ-2EFK-QXMA-47JG","status":"DRAFT","detail":{"reference":"\u003cThe reference data. Includes a post office (PO) number.\u003e","currency_code":"USD","note":"\u003cA note to the invoice recipient. Also appears on the invoice notification email.\u003e","memo":"\u003cA private bookkeeping note for merchant.\u003e","invoice_number":"1644271853","invoice_date":"2022-01-04","payment_term":{"due_date":"2022-01-14"},"viewed_by_recipient":false,"group_draft":false,"metadata":{"create_time":"2022-02-07T22:10:53Z"}},"primary_recipients":[{"billing_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"},"email_address":"foobuyer@gmail.com"},"shipping_info":{"name":{"given_name":"Stephanie","surname":"Meyers","full_name":"Stephanie Meyers"}}}],"amount":{"currency_code":"USD","value":"198.21"},"due_amount":{"currency_code":"USD","value":"198.21"},"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-SXKQ-2EFK-QXMA-47JG","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-SXKQ-2EFK-QXMA-47JG/send","rel":"send","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-SXKQ-2EFK-QXMA-47JG","rel":"replace","method":"PUT"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-SXKQ-2EFK-QXMA-47JG","rel":"delete","method":"DELETE"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/invoices/INV2-SXKQ-2EFK-QXMA-47JG/payments","rel":"record-payment","method":"POST"}]}],"links":[{"href":"https://api.sandbox.paypal.com/v2/invoicing/search-invoice?page=1\u0026page_size=10\u0026total_required=true","rel":"self","method":"POST"},{"href":"https://api.sandbox.paypal.com/v2/invoicing/search-invoice?page=2\u0026page_size=10\u0026total_required=true","rel":"next","method":"POST"}]}