SearchInvoices API Operation

API

Last updated: Aug 15th, 7:11am

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.

Example

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:

1curl 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=10

SearchInvoicesRequest Message

Search for an invoice.

RequestEnvelope Fields

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.

SearchInvoicesRequest Fields

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.

SearchParametersType Fields

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: `Web` — The invoice was created on `paypal.com`. `API` — The invoice was created by an Invoicing Service API call.
`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.

DateRangeType Fields

Field	Description
`startDate`	`xs:dateTime` (Optional) Start of the date range.
`endDate`	`xs:dateTime` (Optional) End of the date range.

SearchInvoicesResponse Message

The SearchInvoicesResponse message contains information returned in response to a SearchInvoicesRequest message.

ResponseEnvelope Fields

Field	Description
`ack`	`common:AckCode` Acknowledgment code. Value is: `Success` — The operation completed successfully. `Failure` — The operation failed. `SuccessWithWarning` — The operation completed successfully; however, there is a warning message. `FailureWithWarning` — The operation failed with a warning message.
`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.

SearchInvoicesResponse Fields

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.

InvoiceSummaryListType Fields

Field	Description
`invoice`	`inv:InvoiceSummaryType` Summary of invoice contents.

InvoiceSummaryType Fields

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.

PPFault Message

The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs.

FaultMessage Fields

Field	Description
`error`	`common:ErrorData` Detailed error information.
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.

ErrorData Fields

Field	Description
`category`	`common:ErrorCategory` The location where the error occurred. Value is: `System` — The system encountered errors; try again `Application` — The application encountered errors; try again `Request` — The request was incorrect
`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: `Error` — Processing of the request was interrupted `Warning` — Processing of the request was completed
`subdomain`	This field is not used.

ResponseEnvelope Fields

Field	Description
`ack`	`common:AckCode` Acknowledgment code. Value is: `Success` — The operation completed successfully. `Failure` — The operation failed. `SuccessWithWarning` — The operation completed successfully; however, there is a warning message. `FailureWithWarning` — The operation failed with a warning message.
`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.

SearchInvoices API Errors

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.