SearchInvoices API Operation

APIDeprecatedLast updated: October 12th 2021, @ 6:58:00 pm


Important: The Adaptive Platform API is not available for new integrations. PayPal provides this documentation to support existing integrations.

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:

curl https://svcs.sandbox.paypal.com/Invoice/SearchInvoices \ -s \ --insecure \ -H "X-PAYPAL-SECURITY-USERID: Your_API_username" \ -H "X-PAYPAL-SECURITY-PASSWORD: Your_API_password" \ -H "X-PAYPAL-SECURITY-SIGNATURE: Your_API_signature" \ -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \ -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \ -H "X-PAYPAL-APPLICATION-ID: Your_AppID"  \ -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

CodeMessageAdditional Information
520002Internal error.
520003Authentication failed. API credentials are incorrect.
520009Account is restricted.
570058Authentication failed. User account is not confirmed.
580022This error code corresponds to validation error messages that deal with errors of supplied parameters.