On this page
No Headings
Last updated: June 12, 2026
Important: The Adaptive Platform API is not available for new integrations. PayPal provides this documentation to support existing integrations. If you're starting an integration, we recommend our latest solutions.
Searches for an invoice.
This example calls SearchInvoices to search for invoices. You
must have created the original invoice either for yourself or on behalf of
another merchant.
PayPal can return a maximum of 100 invoices per page. In this example, only
the first 10 invoices that you created using the Invoicing Service API for the
jb-us-seller1@paypal.com account are returned:
curl https://svcs.sandbox.paypal.com/Invoice/SearchInvoices \ -s \ --insecure \ -H "X-PAYPAL-SECURITY-USERID: " \ -H "X-PAYPAL-SECURITY-PASSWORD: " \ -H "X-PAYPAL-SECURITY-SIGNATURE: " \ -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \ -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \ -H "X-PAYPAL-APPLICATION-ID: " \ -d requestEnvelope.errorLanguage=en_US \ -d merchantEmail=jb-us-seller1%40paypal.com \ -d parameters.origin=API \ -d parameters.email=jb-us-seller1%40paypal.com \ -d page=1 \ -d pageSize=10Search for an invoice.
| Field | Description |
|---|---|
detailLevel | common:DetailLevelCode (Optional) Level of detail required by the client application pertaining to a particular data component. The detail level is specified as a detail level code, which has all the enumerated values of the detail level for the component. By default, the detail level code is ReturnAll, which provides the maximum level of detail. |
errorLanguage | xs:string (Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported. |
| Field | Description |
|---|---|
requestEnvelope | common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned. |
merchantEmail | xs:string (Required) Email address of invoice creator. |
parameters | inv:SearchParametersType (Required) Parameters constraining the search. |
page | xs:integer (Required) Page number of result set, starting with 1. |
pageSize | xs:integer (Required) Number of results per page, between 1 and 100. |
| Field | Description |
|---|---|
email | xs:string (Optional) Email search string. |
recipientName | xs:string (Optional) Recipient search string. |
businessName | xs:string (Optional) Company search string. |
invoiceNumber | xs:string (Optional) Invoice number search string. |
status | inv:statusType (Optional) Invoice status search. |
lowerAmount | xs:decimal (Optional) Invoice amount search. It specifies the smallest amount to be returned. If you pass a value for this field, you must also pass a currencyCode value. |
upperAmount | xs:decimal (Optional) Invoice amount search. It specifies the largest amount to be returned. If you pass a value for this field, you must also pass a currencyCode value. |
currencyCode | xs:string (Optional) Currency used for lower and upper amounts. It is required when you specify lowerAmount or upperAmount. |
memo | xs:string (Optional) Invoice memo search string. |
origin | inv:originType (Optional) Indicates whether the invoice was created by the website or by an API call. Value is:
|
invoiceDate | inv:dateRangeType (Optional) Invoice date range filter. |
dueDate | inv:dateRangeType (Optional) Invoice due date range filter. |
paymentDate | inv:dateRangeType (Optional) Invoice payment date range filter. |
creationDate | inv:dateRangeType (Optional) Invoice creation date range filter. |
| Field | Description |
|---|---|
startDate | xs:dateTime (Optional) Start of the date range. |
endDate | xs:dateTime (Optional) End of the date range. |
The SearchInvoicesResponse message contains information returned
in response to a SearchInvoicesRequest message.
| Field | Description |
|---|---|
ack | common:AckCode Acknowledgment code. Value is:
|
build | xs:string Build number. It is used only by PayPal Merchant Technical Support. |
correlationId | xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
timestamp | xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.774-07:00 Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
| Field | Description |
|---|---|
responseEnvelope | common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgment status. |
count | xs:integer Number of invoices that matched the request. |
invoiceList | inv:invoiceSummaryList Page of invoice summaries that matched the list. |
page | xs:string URL location where the merchant views invoice details. |
hasNextPage | xs:boolean True if another page of invoice summary results exists. |
hasPreviousPage | xs:boolean True if a previous page of the invoice summary results exists. |
| Field | Description |
|---|---|
invoice | inv:InvoiceSummaryType Summary of invoice contents. |
| Field | Description |
|---|---|
invoiceID | xs:string ID of the invoice. |
merchantEmail | xs:string Merchant email address. |
payerEmail | xs:string Payer email address. |
number | xs:string Unique identifier for the invoice. |
billingBusinessName | xs:string Company contact information of the merchant company sending the invoice. |
billingFirstName | xs:string First name of the business information. |
billingLastName | xs:string Last name of the business information. |
shippingBusinessName | xs:string Business name of the shipping information. |
shippingFirstName | xs:string First name of the shipping information. |
shippingLastName | xs:string Last name of the shipping information. |
totalAmount | xs:decimal Total amount of the invoice. |
currencyCode | xs:string Currency used for all invoice item amounts and totals. |
invoiceDate | xs:dateTime Date on which the invoice is enabled. |
dueDate | xs:dateTime Date on which the invoice payment is due. |
status | xs:statusType Status of the invoice. |
referrerCode | xs:string Build Notification (BN) code for tracking transactions with a particular partner. |
origin | inv:originType Indicates whether the invoice was created by the website or by an API call. |
The PPFaultMessage returns ErrorData and the
ResponseEnvelope information to your application if an error
occurs.
| Field | Description |
|---|---|
error | common:ErrorData Detailed error information. |
responseEnvelope | common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgment status. |
| Field | Description |
|---|---|
category | common:ErrorCategory The location where the error occurred. Value is:
|
domain | xs:string The domain to which this service belongs. |
errorId | xs:long A 6-digit number that uniquely identifies a particular error. |
exceptionID | This field is not used. |
message | xs:string A description of the error. |
parameter | common:ErrorParameter Represents contextual information about the error. |
severity | common:ErrorSeverity The severity of the error encountered. Value is:
|
subdomain | This field is not used. |
| Field | Description |
|---|---|
ack | common:AckCode Acknowledgment code. Value is:
|
build | xs:string Build number. It is used only by PayPal Merchant Technical Support. |
correlationId | xs:string Correlation identifier. It is a 13-character alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
timestamp | xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.774-07:00 Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
| Code | Message | Additional Information |
|---|---|---|
| 520002 | Internal error. | |
| 520003 | Authentication failed. API credentials are incorrect. | |
| 520009 | Account is restricted. | |
| 570058 | Authentication failed. User account is not confirmed. | |
| 580022 | This error code corresponds to validation error messages that deal with errors of supplied parameters. |