Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
4. Examine the response and verify that the ACK field contains SUCCESS.
NOTE: You can combine the creation and transmission of an invoice in the same request,
which is CreateAndSend. After you create the request, send it to the
https://svcs.paypal.com/Invoice/CreateA ndSendInvoice endpoint.
Invoicing Service API GuideMay 201211
Introduction to the Invoicing Service API
1
5. If the SendInvoice request was successful, PayPal sends an invoice by email to the payer
whose email you specified in the CreateInvoice or CreateAndSendInvoice request.
6. When your customer clicks Pay Invoice in the email, the customer’s browser is redirected
to PayPal and the customer is prompted to log in.
7. The customer can then pay on PayPal.
The contents of an invoice depend on what you specify in the CreateInvoice, or
CreateAndSend requests. Following is an example invoice:
12May 2012Invoicing Service API Guide
Introduction to the Invoicing Service API
Sending Invoices on Behalf of a Merchant
Sending Invoices on Behalf of a Merchant
You can send invoices on behalf of a merchant if you have permission to do so. There is no
difference in how you set up your request for CreateInvoice or
CreateAndSendInvoice, except that you specify the merchant’s email address instead of
your own in the request, and you include an additional header that indicates you have the
permission of the third party to send invoices on their behalf.
The merchant grants you permission using their PayPal profile, or you request permission
using the Permissions Service API. For more information about this API, see PayPal Permissions Service at
PayPal Permissions Service.
Invoicing Service API Operations
The operations in the Invoicing Service API enable you to create and send invoices to your
customers, as well manage existing invoices, which may or may not have been sent.
1
NOTE: Although you do not need to register your application with PayPal, you must have a
valid app ID to use the Invoicing Service API. If you have an existing app ID, you can
reuse it. See
x.com to obtain an app ID.
Creating and Sending Invoices
API OperationDescription
CreateInvoiceCreates a new invoice.
SendInvoiceSends an invoice to a customer.
CreateAndSendInvoiceCreates and sends an invoice, which is equivalent to the combination
of the CreateInvoice operation followed by the SendInvoice
operation.
Managing Invoices
API OperationDescription
UpdateInvoiceUpdates an invoice.
GetInvoiceDetailsObtains the contents of an invoice.
CancelInvoiceCancels an invoice.
SearchInvoicesSearches for invoices based on specified criteria.
MarkInvoiceAsPaidMarks an invoice as having been paid.
Invoicing Service API GuideMay 201213
Introduction to the Invoicing Service API
1
IPN Variables for Invoicing API Operations
API OperationDescription
MarkInvoiceAsUnpaidMarks an invoice as unpaid.
MarkInvoiceAsRefundedMarks an invoice as having been refunded.
IPN Variables for Invoicing API Operations
PayPal sends IPN messages for invoice payments and canceled invoices. For more
information about IPN, see the Instant Payment Notification Guide:
https://cms.paypal.com/cms_content/US/en_US/files/developer/IPNGuide.pdf.
Invoice Payments
mc_gross: 37.12
protection_eligibility: Eligib le
address_status: confirmed
payer_id: ABF644D44GSPJ
address_street: 5656 South Mar ket Street
payment_date: 15:57:39 Sep 12, 2011 PDT
payment_status: Completed
invoice_id: INV2-VMYW-LQKA-QBGC-6 YDE
charset: windows-1252
address_zip: 95131
first_name: Nick
mc_fee: 1.38
address_country_code: US
address_name: Selling Fruits
notify_version: 3.4
payer_status: verified
business: jbui-us-business1@pa ypal.com
address_country: United States
address_city: San Jose
verify_sign: AFcWxV21C7fd0v3bY YYRCpSSRl31A23x28h wIQCThw2nNi2s8MlV2o10
payer_email: jbui-us-personal1 @paypal.com
txn_id: 68H067535A2789915
payment_type: instant
last_name: Ronald
address_state: CA
merchant_business_name: Fruits Packaging Inc.
merchant_first_name: Joan
notify_version: 3.4
txn_type: invoice_payer_cancel
invoice_number: 0021
charset: windows-1252
payer_email: jbui-us-personal1 @paypal.com
payer_last_name: Bond
merchant_last_name: Joan
payer_first_name: Henry
merchant_email: jbui-us-busine ss1@paypal.com
verify_sign: AiPC9BjkCyDFQXbSk oZcgqH3hpacAAV9zVN I.GLTI1sLOHpeeWp3oMQZ
invoice_id: INV2-UHWN-STXM-65B7-P T4R
ipn_track_id: 2eKZJ-cZftAHzSWbsS7 qjQ
Introduction to the Invoicing Service API
IPN Variables for Invoicing API Operations
1
Invoicing Service API GuideMay 201215
Introduction to the Invoicing Service API
1
IPN Variables for Invoicing API Operations
16May 2012Invoicing Service API Guide
Invoicing Service API Examples
2
You can use the Invoicing Service API to create, send, update, cancel, or obtain details of
invoices for yourself or third-party merchants. You can also search invoices, and mark them as
paid, unpaid, or refunded.
HTTP Headers
Each request message includes HTTP headers specifying authentication, the application ID,
the device ID or IP address, and the payload format or protocol (SOAP).
Adaptive Payments supports request bodies with JSON, NVP, and XML data formats for
REST implementations. You can specify different formats for the request and response, such
as sending the request in JSON and requesting an XML response.
For SOAP, you must also include a specific SOAP protocol header (see the SOAP messages
section).
The following is an example of HTTP headers for NVP in Java for a web implementation:
Use your PayPal account API credentials to authenticate your application. Your API
credentials include an API username and API password. If you are using 3-token
authentication, you must also specify an API signature. If you are using a certificate, the
certificate is used with the username and password; the signature is not used. To specify API
credentials, include the following HTTP headers in your request message (observing case
sensitivity):
Invoicing Service API GuideMay 201217
Invoicing Service API Examples
2
HTTP Headers
HTTP Headers for Authentication
Header Description
X-PAYPAL-SECURITY-USERID Your API username
X-PAYPAL-SECURITY-PASSWORD Your API password
X-PAYPAL-SECURITY-SIGNATURE Your API signature, which is required only if you use 3-
token authorization; a certificate does not use a signature
X-PAYPAL-SECURITY-SUBJECTThird-party permission specification, which specifies the
email address or phone number (for mobile) of the party on
whose behalf you are calling the API operation. The subject
must grant you third-party access in their PayPal profile.
NOTE: Resources specified by the API operation, such as a
payment or preapproval identified b y a key, must be
owned by the subject granting the third-party
permission.
Specifying JSON, NVP, or XML Data Formats
Use the HTTP header X-PAYPAL-REQUEST-DATA-FORMAT to specify the data format the
request body. You can send messages using JSON, NVP or straight XML.
Use the and X-PAYPAL-RESPONSE-DATA-FORM AT headers to specify the data format for the
response.
For SOAP messages, refer to the next section.
HTTP Headers for JSON, NVP, and XML Data Formats
HeaderDescription
X-PAYPAL-REQUEST-DATA-FORMATThe payload format for the request.
Allowable values are:
NV – Name-value pairs
XML – Extensible markup language
JSO N – JavaScript object notation
X-PAYPAL-RESPONSE-DATA-FORMATThe payload format for the response.
Allowable values are:
NV – Name-value pairs
XML – Extensible markup language
JSO N – JavaScript object notation
18May 2012Invoicing Service API Guide
SOAP Messages
To use Adaptive Payments with SOAP, include the HTTP headers for authentication as
described in the section Authentication and the application ID as described in the next section.
In addition, include the X-PAYPAL-MESSAGE-PROTOCOL header with a SOAP11 value.
The following is a header example for an Adaptive Payments API call for a SOAP message:
This example shows how to send an invoice using SendInvoice. The invoice ID, which is in
the response to CreateInvoice, identifies the invoice to send.
curl -s --insecure
-H "X-PAYPAL-SECURITY-USERID: Y our_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD : Y our_API_password"
-H "X-PAYPAL-SECURITY-SIGNATUR E: Y our_API_signature"
This example shows how to send an invoice using UpdateInvoice. If the invoice has not
been sent, the invoice continues to be a draft; otherwise, the invoice is resent.
NOTE: When updating an invoice, in addition to the updated fields, you must also provide all
of the original fields used to create the invoice.
curl -s --insecure
-H "X-PAYPAL-SECURITY-USERID: Y our_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD : Y our_API_password"
-H "X-PAYPAL-SECURITY-SIGNATUR E: Y our_API_signature"
-H "X-PAYPAL-REQUEST-DATA-FORM AT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FOR MAT: NV"
-H "X-PAYPAL-APPLICATION-ID: Your_AppID"
https://sandbox.svcs.paypal.co m/Invoice/UpdateInvoi ce
This example shows how to create and send an invoice using CreateAndSendInvoi ce. 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 -s --insecure
-H "X-PAYPAL-SECURITY-USERID: Y our_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD : Y our_API_password"
-H "X-PAYPAL-SECURITY-SIGNATUR E: Y our_API_signature"
Use the CreateInvoice API operation to create a new invoice. The call includes merchant,
payer, and API caller information, in addition to invoice detail. The response to the call
contains an invoice ID and URL.
CreateInvoiceRequest Message
Use the CreateInvoiceRequest message to create a new invoice. The merchant issuing the
invoice, and the partner, if any, making the call, must have a PayPal account in good standing.
Invoicing Service API GuideMay 201225
CreateInvoice API Operation
3
CreateInvoiceRequest Message
26May 2012Invoicing Service API Guide
CreateInvoice API Operation
CreateInvoiceRequest Message
3
Invoicing Service API GuideMay 201227
CreateInvoice API Operation
3
CreateInvoiceRequest Message
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
CreateInvoiceRequest Fields
FieldDescription
invoiceinv:InvoiceType
(Required) Merchant, payer, and invoice information.
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
InvoiceType Fields
FieldDescription
merchantEmailxs:string
(Required) Merchant email address.
payerEmailxs:string
(Required) Payer email address.
numberxs:string
(Optional) Unique identifier for the invoice.
merchantInfoinv:BusinessInfoTy pe
Company contact information of the merchant company sending the invoi ce.
itemListinv:InvoiceItemListType
(Required) List of items included in this invoice.
currencyCodexs:string
(Required) Currency used for all invoice item amounts and totals.
invoiceDatexs:dateTime
(Optional) Date on which the invoice is enabled.
28May 2012Invoicing Service API Guide
FieldDescription
dueDatexs:dateTime
(Optional) Date on which the invoice payment is due.
paymentTermsinv:PaymentTermsTy pe
(Required) Terms by which the invoice payment is due. It is one of the
following values:
Du eOnReceipt – Payment is due when the payer receives the invoice.
Du eOnDateSpecified – Payment is due on the date specified in the
invoice.
Ne t10 – Payment is due 10 days from the invoice date.
Ne t15 – Payment is due 15 days from the invoice date.
Ne t30 – Payment is due 30 days from the invoice date.
Ne t45 – Payment is due 45 days from the invoice date.
discountPercentxs:decimal
(Optional) Discount percent applied to the invoice.
discountAmountxs:decimal
(Optional) Discount amount applied to the invoice, if any. If
discountPercent is provided, discountAmoun t is ignored.
CreateInvoice API Operation
CreateInvoiceRequest Message
3
termsxs:string
(Optional) General terms for the invoice.
notexs:string
(Optional) Note to the payer company.
merchantMemoxs:string
(Optional) Memo for bookkeeping that is private to the merchant.
billingInfoinv:BusinessInfoTy pe
(Optional) Billing information for the payer.
shippingInfoinv:BusinessInfoTy pe
(Optional) Shipping information for the payer.
shippingAmountxs:decimal
(Optional) Cost of shipping.
shippingTaxNamexs:string
(Optional) Name of the applicable tax on shipping cost.
shippingTaxRatexs:decimal
(Optional) Rate of the applicable tax on shipping cost.
logoURLxs:string
(Optional) Complete URL to an external image used as the logo, if any.
ReferrerCodexs:string
(Optional) Build Notification (BN) code for tracking transactions with a
particular partner..
Invoicing Service API GuideMay 201229
CreateInvoice API Operation
3
CreateInvoiceRequest Message
FieldDescription
customAmountLabelxs:string
customAmountValuexs:decimal
BusinessInfoType Fields
FieldDescription
firstNamexs:string
lastNamexs:string
Label used to display custom amount value. If a value is entered for
customAmountLabel, then customAmountValu e cannot be empty.
Value of custom amount.If a value is entered for customAmountValue, then
customAmountLabel cannot be empty.
(Optional) First name of the company contact.
(Optional) Last name of the company contact.
businessNamexs:string
(Optional) Company business name.
phonexs:string
(Optional) Phone number for contacting the company.
faxxs:string
(Optional) Fax number used by the company.
websitexs:string
(Optional) Website us ed by the company.
customValuexs:string
(Optional) Custom value to be displayed in the contact information details..
addresscommon:BaseAddress
(Optional) Street address of the company.
BaseAddress Fields
FieldDescription
cityxs:string
(Required) City of the address.
countryCodexs:string
(Required) Country code of the address.
30May 2012Invoicing Service API Guide
FieldDescription
line1xs:string
(Required) First line of the address.
line2xs:string
(Optional) Second line of the street address.
postalCodexs:string
(Optional) Postal code of the address.
statexs:string
(Optional) State for the address.
typexs:string
(Optional) Type of address.
InvoiceItemListType Fields
CreateInvoice API Operation
CreateInvoiceRequest Message
3
FieldDescription
iteminv:InvoiceItemType
(Required) Invoice item.
InvoiceItemType Fields
FieldDescription
namexs:string
(Required) SKU or name of the item.
Character length and limitations: 30 characters maximum
descriptionxs:string,
(Optional) Item description.
datexs:dateTime
(Optional) Date on which the product or service was provided.
quantityxs:decimal
(Required) Item count. Valid values are 0 to 10.000.
unitPricexs:decimal
(Required) Price of the item, in the currency specified by the invoice.
taxNamexs:string
(Optional) Name of the applicable tax.
taxRatexs:decimal
(Optional) Rate of the applicable tax.
Invoicing Service API GuideMay 201231
CreateInvoice API Operation
3
CreateInvoiceResponse Message
CreateInvoiceResponse Message
The CreateInvoiceResponse message contains information returned in response to a
CreateInvoiceRequest message. The response contains an invoice ID and the URL to the
invoice on the PayPal system.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
32May 2012Invoicing Service API Guide
CreateInvoiceResponse Fields
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
invoiceIdxs:string
ID of the created invoice.
invoiceNumberxs:string
Invoice number of the created invoice.
invoiceURLxs:string
URL location where merchants view the invoice details.
totalAmountxs:long
The total amount of the invoice.
CreateInvoice API Operation
PPFault Message
3
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
Invoicing Service API GuideMay 201233
CreateInvoice API Operation
3
PPFault Message
FaultMessage Fields
FieldDescription
errorcommon:ErrorData
Detailed error information.
responseEnvelopecommon:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
ErrorData Fields
FieldDescription
categorycommon:ErrorCategory
The location where the error occurred.
Possible values are:
Sy stem – The system encountered errors; try again
Ap plication – The application encountered errors; try again
Re quest – The request was incorrect
domainxs:string
The domain to which this service belongs.
errorIdxs:long
A 6-digit number that uniquely identifies a particular error.
exceptionIDThis field is not used.
messagexs:string
A description of the error.
parametercommon:ErrorParameter
Represents contextual information about the error.
34May 2012Invoicing Service API Guide
FieldDescription
severitycommon:ErrorSeverity
The severity of the error encountered.
Possible values are:
Er ror – Processing of the request was interrupted
Wa rning – Processing of the request was completed
subdomainThis field is not used.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
CreateInvoice API Operation
PPFault Message
3
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
Invoicing Service API GuideMay 201235
CreateInvoice API Operation
3
CreateInvoice API Errors
CreateInvoice API Errors
CodeMessageAdditional Information
520002Internal error.
520005Authentication failed. API credentials are incorrect.
520009Account is restricted.
570045The number of items exceeds this allowed limit.
570046The due date occurs before the invoice date.
570047The invoice date is earlier than todays date.
570048A tax name can only be associated with one unique tax rate on a
single invoice; the following tax name is associated to different
rates on this invoice.
570049The total amount for the invoice cannot be negative.
570050The merchant’s PayPal account cannot be the same as the
payer’s account; merchant and payer email addresses presently
link to the same account.
570051Invoice cannot have more than 10 different taxes.
570054Invalid token.
570058Invalid token.
570059Invoice number is too long.
580022This error code corresponds to validation error messages that
deal with errors of supplied parameters.
580045Merchant does not have a PayPal account associated with this
email address.
580046An invoice already exists for the merchant with this invoice
number.
36May 2012Invoicing Service API Guide
SendInvoice API Operation
4
Use the SendInvoice API operation to send an invoice to a pa yer , and no tify the payer of the
pending invoice.
SendInvoiceRequest Message
Use the SendInvoiceRequest message to send an invoice to a payer, and notify the payer
of the pending invoice.
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
Invoicing Service API GuideMay 201237
SendInvoice API Operation
4
SendInvoiceResponse Message
SendInvoiceRequest Fields
The table below lists the fields for the SendInvoiceRequest message.
FieldDescription
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
invoiceIDxs:string
(Required) ID of the invoice to send.
SendInvoiceResponse Message
The SendInvoiceResponse message contains information returned in response to a
SendInvoiceRequest message. It indicates whether the invoice was sent successfully.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
38May 2012Invoicing Service API Guide
FieldDescription
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
SendInvoiceResponse Fields
SendInvoice API Operation
SendInvoiceResponse Message
4
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
invoiceIDxs:string
ID of the invoice being sent.
invoiceURLxs:string
Location where merchants view the invoice details.
Invoicing Service API GuideMay 201239
SendInvoice API Operation
4
PPFault Message
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
FaultMessage Fields
FieldDescription
errorcommon:ErrorData
Detailed error information.
responseEnvelopecommon:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
40May 2012Invoicing Service API Guide
ErrorData Fields
FieldDescription
categorycommon:ErrorCategory
The location where the error occurred.
Possible values are:
Sy stem – The system encountered errors; try again
Ap plication – The application encountered errors; try again
Re quest – The request was incorrect
domainxs:string
The domain to which this service belongs.
errorIdxs:long
A 6-digit number that uniquely identifies a particular error.
exceptionIDThis field is not used.
messagexs:string
A description of the error.
SendInvoice API Operation
PPFault Message
4
parametercommon:ErrorParameter
Represents contextual information about the error.
severitycommon:ErrorSeverity
The severity of the error encountered.
Possible values are:
Er ror – Processing of the request was interrupted
Wa rning – Processing of the request was completed
subdomainThis field is not used.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
Invoicing Service API GuideMay 201241
SendInvoice API Operation
4
Send Invoice API Errors
FieldDescription
correlationIdxs:string
timestampxs:datetime
Send Invoice API Errors
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
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.
CodeMessageAdditional Information
520002Internal error.
520005Authentication failed. API credentials are incorrect.
520009Account is restricted.
550026Partner did not create the invoice but attempted to access or
modify it; a merchant’s invoice can be accessed or modified only
by the partner who created it.
550027Merchant cannot access or modify an invoice they did not create;
an invoice can only be accessed or modified by the party who
created it.
570052You cannot send this invoice because it has already been paid.
570053You cannot send this invoice because it has already been
canceled.
570058Invalid token.
570064An invoice that has already been sent cannot be sent again.
580022This error code corresponds to validation error messages that
deal with errors of supplied parameters.
580047Invoice does not exist.
42May 2012Invoicing Service API Guide
CreateAndSendInvoice API
5
Operation
Use the CreateAndSendInvoice API operation to create and send an invoice.
CreateAndSendInvoiceRequest Message
Use the CreateAndSendInvoiceRequest message to create and send a new invoice. The
requester should authenticate the caller and verify that the merchant requesting the invoice has
an existing PayPal account in good standing. Once the invoice is created, PayPal sends it to the
specified payer, who is notified of the pending invoice.
Invoicing Service API GuideMay 201243
CreateAndSendInvoice API Operation
5
CreateAndSendInvoiceRequest Message
44May 2012Invoicing Service API Guide
CreateAndSendInvoice API Operation
CreateAndSendInvoiceRequest Message
5
Invoicing Service API GuideMay 201245
CreateAndSendInvoice API Operation
5
CreateAndSendInvoiceRequest Message
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
CreateAndSendInvoiceRequest Fields
FieldDescription
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
invoiceinv:InvoiceType
(Required) Merchant, payer, and invoice information.
InvoiceType Fields
FieldDescription
merchantEmailxs:string
(Required) Merchant email address.
payerEmailxs:string
(Required) Payer email address.
numberxs:string
(Optional) Unique identifier for the invoice.
merchantInfoinv:BusinessInfoTy pe
Company contact information of the merchant company sending the invoi ce.
itemListinv:InvoiceItemListType
(Required) List of items included in this invoice.
currencyCodexs:string
(Required) Currency used for all invoice item amounts and totals.
invoiceDatexs:dateTime
(Optional) Date on which the invoice is enabled.
46May 2012Invoicing Service API Guide
FieldDescription
dueDatexs:dateTime
(Optional) Date on which the invoice payment is due.
paymentTermsinv:PaymentTermsTy pe
(Required) Terms by which the invoice payment is due. It is one of the
following values:
Du eOnReceipt – Payment is due when the payer receives the invoice.
Du eOnDateSpecified – Payment is due on the date specified in the
invoice.
Ne t10 – Payment is due 10 days from the invoice date.
Ne t15 – Payment is due 15 days from the invoice date.
Ne t30 – Payment is due 30 days from the invoice date.
Ne t45 – Payment is due 45 days from the invoice date.
discountPercentxs:decimal
(Optional) Discount percent applied to the invoice.
discountAmountxs:decimal
(Optional) Discount amount applied to the invoice, if any. If
discountPercent is provided, discountAmoun t is ignored.
CreateAndSendInvoice API Operation
CreateAndSendInvoiceRequest Message
5
termsxs:string
(Optional) General terms for the invoice.
notexs:string
(Optional) Note to the payer company.
merchantMemoxs:string
(Optional) Memo for bookkeeping that is private to the merchant.
billingInfoinv:BusinessInfoTy pe
(Optional) Billing information for the payer.
shippingInfoinv:BusinessInfoTy pe
(Optional) Shipping information for the payer.
shippingAmountxs:decimal
(Optional) Cost of shipping.
shippingTaxNamexs:string
(Optional) Name of the applicable tax on shipping cost.
shippingTaxRatexs:decimal
(Optional) Rate of the applicable tax on shipping cost.
logoURLxs:string
(Optional) Complete URL to an external image used as the logo, if any.
ReferrerCodexs:string
(Optional) Build Notification (BN) code for tracking transactions with a
particular partner..
Invoicing Service API GuideMay 201247
CreateAndSendInvoice API Operation
5
CreateAndSendInvoiceRequest Message
FieldDescription
customAmountLabelxs:string
customAmountValuexs:decimal
BusinessInfoType Fields
FieldDescription
firstNamexs:string
lastNamexs:string
Label used to display custom amount value. If a value is entered for
customAmountLabel, then customAmountValu e cannot be empty.
Value of custom amount.If a value is entered for customAmountValue, then
customAmountLabel cannot be empty.
(Optional) First name of the company contact.
(Optional) Last name of the company contact.
businessNamexs:string
(Optional) Company business name.
phonexs:string
(Optional) Phone number for contacting the company.
faxxs:string
(Optional) Fax number used by the company.
websitexs:string
(Optional) Website us ed by the company.
customValuexs:string
(Optional) Custom value to be displayed in the contact information details..
addresscommon:BaseAddress
(Optional) Street address of the company.
BaseAddress Fields
FieldDescription
cityxs:string
(Required) City of the address.
countryCodexs:string
(Required) Country code of the address.
48May 2012Invoicing Service API Guide
FieldDescription
line1xs:string
(Required) First line of the address.
line2xs:string
(Optional) Second line of the street address.
postalCodexs:string
(Optional) Postal code of the address.
statexs:string
(Optional) State for the address.
typexs:string
(Optional) Type of address.
InvoiceItemListType Fields
CreateAndSendInvoice API Operation
CreateAndSendInvoiceRequest Message
5
FieldDescription
iteminv:InvoiceItemType
(Required) Invoice item.
InvoiceItemType Fields
FieldDescription
namexs:string
(Required) SKU or name of the item.
Character length and limitations: 30 characters maximum
descriptionxs:string,
(Optional) Item description.
datexs:dateTime
(Optional) Date on which the product or service was provided.
quantityxs:decimal
(Required) Item count. Valid values are 0 to 10.000.
unitPricexs:decimal
(Required) Price of the item, in the currency specified by the invoice.
taxNamexs:string
(Optional) Name of the applicable tax.
taxRatexs:decimal
(Optional) Rate of the applicable tax.
Invoicing Service API GuideMay 201249
CreateAndSendInvoice API Operation
5
CreateAndSendInvoiceResponse Message
CreateAndSendInvoiceResponse Message
The CreateAnd SendInvoiceResponse message contains information returned in response
to a CreateAndSendInvoiceRequest message. The response contains an invoice ID and
the URL to the invoice on the PayPal system, and indicates whether the invoice was sent
successfully.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
50May 2012Invoicing Service API Guide
CreateAndSendInvoiceResponse Fields
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
invoiceIDxs:string
ID of the created invoice.
invoiceNumberxs:string
Number of the created invoice.
invoiceURLxs:string
URL location where merchants view the invoice details.
totalAmountxs:long
The total amount of the invoice.
CreateAndSendInvoice API Operation
PPFault Message
5
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
Invoicing Service API GuideMay 201251
CreateAndSendInvoice API Operation
5
PPFault Message
FaultMessage Fields
FieldDescription
errorcommon:ErrorData
Detailed error information.
responseEnvelopecommon:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
ErrorData Fields
FieldDescription
categorycommon:ErrorCategory
The location where the error occurred.
Possible values are:
Sy stem – The system encountered errors; try again
Ap plication – The application encountered errors; try again
Re quest – The request was incorrect
domainxs:string
The domain to which this service belongs.
errorIdxs:long
A 6-digit number that uniquely identifies a particular error.
exceptionIDThis field is not used.
messagexs:string
A description of the error.
parametercommon:ErrorParameter
Represents contextual information about the error.
52May 2012Invoicing Service API Guide
FieldDescription
severitycommon:ErrorSeverity
The severity of the error encountered.
Possible values are:
Er ror – Processing of the request was interrupted
Wa rning – Processing of the request was completed
subdomainThis field is not used.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
CreateAndSendInvoice API Operation
CreateAndSendInvoice API Errors
5
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
CreateAndSendInvoice API Errors
CodeMessageAdditional Information
520002Internal error.
Invoicing Service API GuideMay 201253
CreateAndSendInvoice API Operation
5
CreateAndSendInvoice API Errors
CodeMessageAdditional Information
520005Authentication failed. API credentials are incorrect.
520009Account is restricted.
570045The number of items exceeds this allowed limit.
570046The due date occurs before the invoice date.
570047The invoice date is earlier than todays date.
570048A tax name can only be associated with one unique tax rate on a
single invoice; the following tax name is associated to different
rates on this invoice.
570049The total amount for the invoice cannot be negative.
570050The merchant’s PayPal account cannot be the same as the
payer’s account; merchant and payer email addresses presently
link to the same account.
570051Invoice cannot have more than 10 different taxes.
570054Invalid token.
570058Invalid token.
570059Invoice number is too long.
580022This error code corresponds to validation error messages that
deal with errors of supplied parameters.
580045Merchant does not have a PayPal account associated with this
email address.
580046An invoice already exists for the merchant with this invoice
number.
54May 2012Invoicing Service API Guide
UpdateInvoice API Operation
6
Use the UpdateInvoice API operation to update an invoice.
UpdateInvoiceRequest Message
Use the UpdateInvoiceRequest message to update an invoice.
Invoicing Service API GuideMay 201255
UpdateInvoice API Operation
6
UpdateInvoiceRequest Message
56May 2012Invoicing Service API Guide
UpdateInvoice API Operation
UpdateInvoiceRequest Message
6
Invoicing Service API GuideMay 201257
UpdateInvoice API Operation
6
UpdateInvoiceRequest Message
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
UpdateInvoiceRequest Fields
FieldDescription
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
invoiceIDxs:string
(Required) ID of the invoice to update.
invoiceinv:InvoiceType
(Required) Merchant, payer, and invoice information.
InvoiceType Fields
FieldDescription
merchantEmailxs:string
(Required) Merchant email address.
payerEmailxs:string
(Required) Payer email address.
numberxs:string
(Optional) Unique identifier for the invoice.
merchantInfoinv:BusinessInfoTy pe
Company contact information of the merchant company sending the invoi ce.
itemListinv:InvoiceItemListType
(Required) List of items included in this invoice.
currencyCodexs:string
(Required) Currency used for all invoice item amounts and totals.
58May 2012Invoicing Service API Guide
FieldDescription
invoiceDatexs:dateTime
(Optional) Date on which the invoice is enabled.
dueDatexs:dateTime
(Optional) Date on which the invoice payment is due.
paymentTermsinv:PaymentTermsTy pe
(Required) Terms by which the invoice payment is due. It is one of the
following values:
Du eOnReceipt – Payment is due when the payer receives the invoice.
Du eOnDateSpecified – Payment is due on the date specified in the
invoice.
Ne t10 – Payment is due 10 days from the invoice date.
Ne t15 – Payment is due 15 days from the invoice date.
Ne t30 – Payment is due 30 days from the invoice date.
Ne t45 – Payment is due 45 days from the invoice date.
discountPercentxs:decimal
(Optional) Discount percent applied to the invoice.
UpdateInvoice API Operation
UpdateInvoiceRequest Message
6
discountAmountxs:decimal
(Optional) Discount amount applied to the invoice, if any. If
discountPercent is provided, discountAmoun t is ignored.
termsxs:string
(Optional) General terms for the invoice.
notexs:string
(Optional) Note to the payer company.
merchantMemoxs:string
(Optional) Memo for bookkeeping that is private to the merchant.
billingInfoinv:BusinessInfoTy pe
(Optional) Billing information for the payer.
shippingInfoinv:BusinessInfoTy pe
(Optional) Shipping information for the payer.
shippingAmountxs:decimal
(Optional) Cost of shipping.
shippingTaxNamexs:string
(Optional) Name of the applicable tax on shipping cost.
shippingTaxRatexs:decimal
(Optional) Rate of the applicable tax on shipping cost.
logoURLxs:string
(Optional) Complete URL to an external image used as the logo, if any.
Invoicing Service API GuideMay 201259
UpdateInvoice API Operation
6
UpdateInvoiceRequest Message
FieldDescription
ReferrerCodexs:string
customAmountLabelxs:string
customAmountValuexs:decimal
BusinessInfoType Fields
FieldDescription
firstNamexs:string
(Optional) Build Notification (BN) code for tracking transactions with a
particular partner..
Label used to display custom amount value. If a value is entered for
customAmountLabel, then customAmountValu e cannot be empty.
Value of custom amount.If a value is entered for customAmountValue, then
customAmountLabel cannot be empty.
(Optional) First name of the company contact.
lastNamexs:string
(Optional) Last name of the company contact.
businessNamexs:string
(Optional) Company business name.
phonexs:string
(Optional) Phone number for contacting the company.
faxxs:string
(Optional) Fax number used by the company.
websitexs:string
(Optional) Website us ed by the company.
customValuexs:string
(Optional) Custom value to be displayed in the contact information details..
addresscommon:BaseAddress
(Optional) Street address of the company.
InvoiceItemType Fields
FieldDescription
iteminv:InvoiceItemType
(Required) Invoice item.
60May 2012Invoicing Service API Guide
InvoiceItemType Fields
FieldDescription
namexs:string
(Required) SKU or name of the item.
Character length and limitations: 30 characters maximum
descriptionxs:string,
(Optional) Item description.
datexs:dateTime
(Optional) Date on which the product or service was provided.
quantityxs:decimal
(Required) Item count. Valid values are 0 to 10.000.
unitPricexs:decimal
(Required) Price of the item, in the currency specified by the invoice.
taxNamexs:string
(Optional) Name of the applicable tax.
UpdateInvoice API Operation
UpdateInvoiceResponse Message
6
taxRatexs:decimal
(Optional) Rate of the applicable tax.
UpdateInvoiceResponse Message
The UpdateInvoiceResponse message contains information returned in response to an
UpdateInvoiceRequest message.
Invoicing Service API GuideMay 201261
UpdateInvoice API Operation
6
UpdateInvoiceResponse Message
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
db87c705a910e) that is used only by PayPal Merchant Technical Support.
NOTE: You must log and store this data for every response you receive.
however, there is a warning message.
PayPal Technical Support uses the information to assist with reported
issues.
timestampxs: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.
UpdateInvoiceResponse Fields
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
invoiceIdxs:string
ID of the updated invoice.
invoiceNumberxs:string
Invoice number of the updated invoice.
invoiceURLxs:string
URL location where merchants view the updated invoice details.
totalAmountxs:long
The total amount of the invoice.
62May 2012Invoicing Service API Guide
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
UpdateInvoice API Operation
PPFault Message
6
FaultMessage Fields
FieldDescription
errorcommon:ErrorData
Detailed error information.
responseEnvelopecommon:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
Invoicing Service API GuideMay 201263
UpdateInvoice API Operation
6
PPFault Message
ErrorData Fields
FieldDescription
categorycommon:ErrorCategory
The location where the error occurred.
Possible values are:
Sy stem – The system encountered errors; try again
Ap plication – The application encountered errors; try again
Re quest – The request was incorrect
domainxs:string
The domain to which this service belongs.
errorIdxs:long
A 6-digit number that uniquely identifies a particular error.
exceptionIDThis field is not used.
messagexs:string
A description of the error.
parametercommon:ErrorParameter
Represents contextual information about the error.
severitycommon:ErrorSeverity
The severity of the error encountered.
Possible values are:
Er ror – Processing of the request was interrupted
Wa rning – Processing of the request was completed
subdomainThis field is not used.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
64May 2012Invoicing Service API Guide
FieldDescription
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
UpdateInvoice API Errors
UpdateInvoice API Operation
UpdateInvoice API Errors
6
CodeMessageAdditional Information
520002Internal error.
520005Authentication failed. API credentials are incorrect.
520009Account is restricted.
550026Partner did not create the invoice but attempted to access or
modify it; a merchant’s invoice can be accessed or modified only
by the partner who created it.
550027Merchant cannot access or modify an invoice they did not create;
an invoice can only be accessed or modified by the party who
created it.
570045The number of items exceeds this allowed limit.
570046The due date occurs before the invoice date.
570047The invoice date is earlier than todays date.
570048A tax name can only be associated with one unique tax rate on a
single invoice; the following tax name is associated to different
rates on this invoice.
570049The total amount for the invoice cannot be negative.
570050The merchant’s PayPal account cannot be the same as the
payer’s account; merchant and payer email addresses presently
link to the same account.
570051Invoice cannot have more than 10 different taxes.
Invoicing Service API GuideMay 201265
UpdateInvoice API Operation
6
UpdateInvoice API Errors
CodeMessageAdditional Information
570058Invalid token.
570059Invoice number is too long.
570060The status of the invoice is such that it can no longer be updated.
580022This error code corresponds to validation error messages that
deal with errors of supplied parameters.
580046An invoice already exists for the merchant with this invoice
number.
580047Invoice does not exist.
66May 2012Invoicing Service API Guide
GetInvoiceDetails API Operation
7
Use the GetInvoiceDetails API operation to get detailed information about an invoice.
GetInvoiceDetailsRequest Message
Use the GetInvoiceDetailsRequest message to get detailed information about an
invoice.
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
Invoicing Service API GuideMay 201267
GetInvoiceDetails API Operation
7
GetInvoiceDetailsResponse Message
GetInvoiceDetailsRequest Fields
FieldDescription
invoiceIDxs:string
(Required) ID of the invoice to retrieve.
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
GetInvoiceDetailsResponse Message
68May 2012Invoicing Service API Guide
GetInvoiceDetails API Operation
GetInvoiceDetailsResponse Message
7
Invoicing Service API GuideMay 201269
GetInvoiceDetails API Operation
7
GetInvoiceDetailsResponse Message
70May 2012Invoicing Service API Guide
GetInvoiceDetails API Operation
GetInvoiceDetailsResponse Message
7
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
Invoicing Service API GuideMay 201271
GetInvoiceDetails API Operation
7
GetInvoiceDetailsResponse Message
FieldDescription
timestampxs: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.
GetInvoiceDetailsResponse Fields
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
invoicexs:string
ID of the created invoice.
invoiceDetailsinv:InvoiceDetailsType
Details about the invoice status and state change dates.
paymentDetailsinv:PaymentDetailsType
Payment details about the invoice.
refundDetailsinv:PaymentRefundDetailsType
The requested invoice refund details.
invoiceURLxs:string
URL location where merchants view the invoice details.
InvoiceType Fields
FieldDescription
merchantEmailxs:string
Merchant email address.
payerEmailxs:string
Payer email address.
numberxs:string
Unique identifier for the invoice.
merchantInfoinv:BusinessInfoTy pe
Company contact information of the merchant company sending the invoi ce.
72May 2012Invoicing Service API Guide
FieldDescription
itemListinv:InvoiceItemListType
List of items included in this invoice.
currencyCodexs:string
Currency used for all invoice item amounts and totals.
invoiceDatexs:dateTime
Date on which the invoice is enabled.
dueDatexs:dateTime
Date on which the invoice payment is due.
paymentTermsinv:PaymentTermsTy pe
Terms by which the invoice payment is due. It is one of the following values:
Du eOnReceipt – Payment is due when the payer receives the invoice.
Du eOnDateSpecified – Payment is due on the date specified in the
invoice.
Ne t10 – Payment is due 10 days from the invoice date.
Ne t15 – Payment is due 15 days from the invoice date.
Ne t30 – Payment is due 30 days from the invoice date.
Ne t45 – Payment is due 45 days from the invoice date.
GetInvoiceDetails API Operation
GetInvoiceDetailsResponse Message
7
discountPercentxs:decimal
Discount percent applied to the invoice.
discountAmountxs:decimal
Discount amount applied to the invoice, if any. If discountPerc ent is
provided, discountAmount is ignored.
termsxs:string
General terms for the invoice.
notexs:string
Note to the payer company.
merchantMemoxs:string
Memo for bookkeeping that is private to the merchant.
billingInfoinv:BusinessInfoTy pe
Billing information for the payer.
shippingInfoinv:BusinessInfoTy pe
Shipping information for the payer.
shippingAmountxs:decimal
Cost of shipping.
shippingTaxNamexs:string
Name of the applicable tax on shipping cost.
Invoicing Service API GuideMay 201273
GetInvoiceDetails API Operation
7
GetInvoiceDetailsResponse Message
FieldDescription
shippingTaxRatexs:decimal
Rate of the applicable tax on shipping cost.
logoURLxs:string
External image URL of the invoice logo, if any.
referrerCodexs:string
Build Notification (BN) code for tracking transactions with a particular
partner.
InvoiceDetailsType Fields
FieldDescription
statusinv:StatusType
Status of the invoice.
totalAmountxs:decimal
Total amount of the invoice (cost of items, shipping, and tax, less any
discount). The invoicing system sets this field and ignores any changes made
by API callers.
origininv:OriginType
Indicates whether the invoice was created by the website or an API call.
createdDatexs:dateTime
Date when the invoice was created.
createdByxs:string
Account that created the invoice.
canceledDatexs:dateTime
Date when the invoice was canceled, if canceled.
canceledByActorxs:ActorType
Actor who canceled the invoice.
canceledByxs:string
Account that canceled the invoice.
lastUpdatedDatexs:dateTime
Date when the invoice was last updated.
lastUpdatedByxs:string
Account that last edited the invoice.
firstSentDatexs:dateTime
Date when the invoice was first sent.
74May 2012Invoicing Service API Guide
FieldDescription
lastSentDatexs:dateTime
Date when the invoice was last sent.
lastSentByxs:string
Account that last sent the invoice.
paidDatexs:dateTime
Date when the invoice was paid, if paid.
PaymentDetailsType Fields
FieldDescription
viaPayPalxs:boolean
Returns True if the invoice was paid by PayPal.
paypalPaymentinv:PayPalPaymentDetailsType
PayPal payment details about the invoice.
GetInvoiceDetails API Operation
GetInvoiceDetailsResponse Message
7
otherPaymentinv:OtherPaymentDe tailsType
Offline payment details about the invoice.
PayPalPaymentDetailsType Fields
FieldDescription
transactionIDxs:string
Transaction ID of the PayPal payment.
datexs:dateTime
Date when the invoice was paid.
Invoicing Service API GuideMay 201275
GetInvoiceDetails API Operation
7
PPFault Message
OtherPaymentDetailsType Fields
FieldDescription
methodinv:PaymentMethodsType
(Optional) Method that can be used to mark an invoice as paid when the payer
pays offline. It is one of the following values:
Ba nkTransfer – Payment is made by a bank transfer.
Ca sh – Payment is made in cash.
Ch eck – Payment is made by check.
Cr editCard – Payment is made by a credit card.
De bitCard – Payment is made by a debit card.
Ot her – Payment is made by a method not specified in this list.
Pa yPal – Payment is made by PayPal.
Wi reTransfer – Payment is made by a wire transfer.
notexs:string
(Optional) Optional note associated with the payment.
datexs:dateTime
(Required) Date when the invoice was paid.
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
76May 2012Invoicing Service API Guide
FaultMessage Fields
FieldDescription
errorcommon:ErrorData
Detailed error information.
GetInvoiceDetails API Operation
PPFault Message
7
responseEnvelopecommon:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
ErrorData Fields
FieldDescription
categorycommon:ErrorCategory
The location where the error occurred.
Possible values are:
Sy stem – The system encountered errors; try again
Ap plication – The application encountered errors; try again
Re quest – The request was incorrect
domainxs:string
The domain to which this service belongs.
errorIdxs:long
A 6-digit number that uniquely identifies a particular error.
exceptionIDThis field is not used.
messagexs:string
A description of the error.
parametercommon:ErrorParameter
Represents contextual information about the error.
Invoicing Service API GuideMay 201277
GetInvoiceDetails API Operation
7
GetInvoiceDetails API Errors
FieldDescription
severitycommon:ErrorSeverity
The severity of the error encountered.
Possible values are:
Er ror – Processing of the request was interrupted
Wa rning – Processing of the request was completed
subdomainThis field is not used.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
GetInvoiceDetails API Errors
CodeMessageAdditional Information
520002Internal error.
78May 2012Invoicing Service API Guide
GetInvoiceDetails API Operation
GetInvoiceDetails API Errors
CodeMessageAdditional Information
520005Authentication failed. API credentials are incorrect.
520009Account is restricted.
550026Partner did not create the invoice but attempted to access or
modify it; a merchant’s invoice can be accessed or modified only
by the partner who created it.
550027Merchant cannot access or modify an invoice they did not create;
an invoice can only be accessed or modified by the party who
created it.
570058Invalid token.
580022This error code corresponds to validation error messages that
deal with errors of supplied parameters.
580047Invoice does not exist.
7
Invoicing Service API GuideMay 201279
GetInvoiceDetails API Operation
7
GetInvoiceDetails API Errors
80May 2012Invoicing Service API Guide
CancelInvoice API Operation
8
Use the CancelInvoice API operation to cancel an invoice.
CancelInvoiceRequest Message
Use the CancelInvoiceRequest message to cancel an invoice.
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
Invoicing Service API GuideMay 201281
CancelInvoice API Operation
8
CancelInvoiceResponse Message
CancelInvoiceRequest Fields
FieldDescription
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
invoiceIDxs:string
(Optional) ID of the invoice.
subjectxs:string
(Optional) Subject of the cancelation notification.
noteForPayerxs:string
(Optional) Note to send payer within the cancelation notification.
sendCopyToMerchantxs:boolean
(Optional) Indicates whether to send a copy of the cancelation notification to
the merchant. It is one of the following values:
fa lse – Do not send a copy of the cancelation notification to the merchant
(default).
tr ue – Send a copy of the cancelation notification to the merchant.
CancelInvoiceResponse Message
Use the CancelInvoiceResponse message to cancel an invoice.
82May 2012Invoicing Service API Guide
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
CancelInvoice API Operation
CancelInvoiceResponse Message
8
timestampxs: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.
CancelInvoiceResponse Fields
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
invoiceIDxs:string
ID of the canceled invoice.
invoiceNumberxs:string
Number of the canceled invoice.
invoiceURLxs:string
URL location where merchants view the invoice details.
Invoicing Service API GuideMay 201283
CancelInvoice API Operation
8
PPFault Message
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
FaultMessage Fields
FieldDescription
errorcommon:ErrorData
Detailed error information.
responseEnvelopecommon:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
84May 2012Invoicing Service API Guide
ErrorData Fields
FieldDescription
categorycommon:ErrorCategory
The location where the error occurred.
Possible values are:
Sy stem – The system encountered errors; try again
Ap plication – The application encountered errors; try again
Re quest – The request was incorrect
domainxs:string
The domain to which this service belongs.
errorIdxs:long
A 6-digit number that uniquely identifies a particular error.
exceptionIDThis field is not used.
messagexs:string
A description of the error.
CancelInvoice API Operation
PPFault Message
8
parametercommon:ErrorParameter
Represents contextual information about the error.
severitycommon:ErrorSeverity
The severity of the error encountered.
Possible values are:
Er ror – Processing of the request was interrupted
Wa rning – Processing of the request was completed
subdomainThis field is not used.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
Invoicing Service API GuideMay 201285
CancelInvoice API Operation
8
CancelInvoice API Errors
FieldDescription
correlationIdxs:string
timestampxs:datetime
CancelInvoice API Errors
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
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.
CodeMessageAdditional Information
520002Internal error.
520005Authentication failed. API credentials are incorrect.
520009Account is restricted.
550026Partner did not create the invoice but attempted to access or
modify it; a merchant’s invoice can be accessed or modified only
by the partner who created it.
550027Merchant cannot access or modify an invoice they did not create;
an invoice can only be accessed or modified by the party who
created it.
570058Invalid token.
570061Invoice cannot be canceled since it has already been paid.
570062The invoice has already been canceled.
570063A draft invoice cannot be canceled.
580022This error code corresponds to validation error messages that
deal with errors of supplied parameters.
580047Invoice does not exist.
86May 2012Invoicing Service API Guide
SearchInvoices API Operation
9
Use the SearchInvoice API operation to search an invoice.
SearchInvoicesRequest Message
Use the SearchInvoiceRequest message to search an invoice.
Invoicing Service API GuideMay 201287
SearchInvoices API Operation
9
SearchInvoicesRequest Message
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs: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
FieldDescription
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
merchantEmailxs:string
(Required) Email address of invoice creator.
parametersinv:SearchParamete rsType
(Required) Parameters constraining the search.
88May 2012Invoicing Service API Guide
FieldDescription
pagexs:integer
(Required) Page number of result set, starting with 1.
pageSizexs:integer
(Required) Number of results per page, between 1 and 100.
SearchParametersType Fields
FieldDescription
emailxs:string
(Optional) Email search string.
recipientNamexs:string
(Optional) Recipient search string.
businessNamexs:string
(Optional) Company search string.
SearchInvoices API Operation
SearchInvoicesRequest Message
9
invoiceNumberxs:integer
(Optional) Invoice number search string.
statusinv:statusType
(Optional) Invoice status search.
lowerAmountxs: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.
upperAmountxs: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.
currencyCodexs:string
(Optional) Currency used for lower and upper amounts. It is required when
you specify lowerAmount or upperAmount.
memoxs:string
(Optional) Invoice memo search string.
origininv:originType
(Optional) Indicates whether the invoice was created by the website or by an
API call. It is one of the following values:
We b – The invoice was created on paypal.com.
AP I – The invoice was created by an Invoicing Service API call.
Invoicing Service API GuideMay 201289
SearchInvoices API Operation
9
SearchInvoicesResponse Message
FieldDescription
invoiceDateinv:dateRangeType
(Optional) Invoice date range filter.
dueDateinv:dateRangeType
(Optional) Invoice due date range filter.
paymentDateinv:dateRangeType
(Optional) Invoice payment date range filter.
creationDateinv:dateRangeType
(Optional) Invoice creation date range filter.
DateRangeType Fields
FieldDescription
startDatexs:dateTime
(Optional) Start of the date range.
endDatexs:dateTime
(Optional) End of the date range.
SearchInvoicesResponse Message
The SearchInvoicesResponse message contains information returned in response to a
SearchInvoicesRequest message.
90May 2012Invoicing Service API Guide
SearchInvoices API Operation
SearchInvoicesResponse Message
9
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
Invoicing Service API GuideMay 201291
SearchInvoices API Operation
9
SearchInvoicesResponse Message
FieldDescription
correlationIdxs:string
timestampxs:datetime
SearchInvoicesResponse Fields
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
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.
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
countxs:integer
Number of invoices that matched the request.
invoiceListinv:invoiceSummary List
Page of invoice summaries that matched the list.
pagexs:string
URL location where the merchant views invoice details.
hasNextPagexs:boolean
True if another page of invoice summary results exists.
hasPreviousPagexs:boolean
True if a previous page of the invoice summary results exists.
InvoiceSummaryListType Fields
FieldDescription
invoiceinv:InvoiceSummaryType
Summary of invoice contents.
92May 2012Invoicing Service API Guide
InvoiceSummaryType Fields
FieldDescription
invoiceIDxs:string
ID of the invoice.
merchantEmailxs:string
Merchant email address.
payerEmailxs:string
Payer email address.
numberxs:string
Unique identifier for the invoice.
billingBusinessNamexs:string
Company contact information of the merchant company sending the invoi ce.
Currency used for all invoice item amounts and totals.
invoiceDatexs:dateTime
Date on which the invoice is enabled.
dueDatexs:dateTime
Date on which the invoice payment is due.
statusxs:statusType
Status of the invoice.
referrerCodexs:string
Build Notification (BN) code for tracking transactions with a particular
partner.
origininv:originType
Indicates whether the invoice was created by the website or by an API call.
Invoicing Service API GuideMay 201293
SearchInvoices API Operation
9
PPFault Message
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
FaultMessage Fields
FieldDescription
errorcommon:ErrorData
Detailed error information.
responseEnvelopecommon:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
94May 2012Invoicing Service API Guide
ErrorData Fields
FieldDescription
categorycommon:ErrorCategory
The location where the error occurred.
Possible values are:
Sy stem – The system encountered errors; try again
Ap plication – The application encountered errors; try again
Re quest – The request was incorrect
domainxs:string
The domain to which this service belongs.
errorIdxs:long
A 6-digit number that uniquely identifies a particular error.
exceptionIDThis field is not used.
messagexs:string
A description of the error.
SearchInvoices API Operation
PPFault Message
9
parametercommon:ErrorParameter
Represents contextual information about the error.
severitycommon:ErrorSeverity
The severity of the error encountered.
Possible values are:
Er ror – Processing of the request was interrupted
Wa rning – Processing of the request was completed
subdomainThis field is not used.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
Invoicing Service API GuideMay 201295
SearchInvoices API Operation
9
SearchInvoices API Errors
FieldDescription
correlationIdxs:string
timestampxs:datetime
SearchInvoices API Errors
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
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.
CodeMessageAdditional Information
520002Internal error.
520005Authentication failed. API credentials are incorrect.
520009Account is restricted.
570058Invalid token.
580022This error code corresponds to validation error messages that
deal with errors of supplied parameters.
96May 2012Invoicing Service API Guide
MarkInvoiceAsPaid API Operation
10
Use the MarkInvoiceAsPaid API operation to mark an invoice as paid.
MarkInvoiceAsPaidRequest Message
Use the MarkInvoiceAsPaidRequest message to mark an invoice as paid.
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
Invoicing Service API GuideMay 201297
10
MarkInvoiceAsPaid API Operation
MarkInvoiceAsPaidRequest Message
FieldDescription
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
MarkInvoiceAsPaidRequest Fields
FieldDescription
invoiceIDxs:string
(Required) ID of the invoice to mark as paid.
paymentinv:OtherPaymentDetailsType
(Required) Details of the payment made against this type.
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
OtherPaymentDetailsType Fields
FieldDescription
methodinv:PaymentMethodsType
(Optional) Method that can be used to mark an invoice as paid when the payer
pays offline. It is one of the following values:
Ba nkTransfer – Payment is made by a bank transfer.
Ca sh – Payment is made in cash.
Ch eck – Payment is made by check.
Cr editCard – Payment is made by a credit card.
De bitCard – Payment is made by a debit card.
Ot her – Payment is made by a method not specified in this list.
Pa yPal – Payment is made by PayPal.
Wi reTransfer – Payment is made by a wire transfer.
notexs:string
(Optional) Optional note associated with the payment.
datexs:dateTime
(Required) Date when the invoice was paid.
98May 2012Invoicing Service API Guide
MarkInvoiceAsPaid API Operation
MarkInvoiceAsPaidResponse Message
MarkInvoiceAsPaidResponse Message
The MarkInvoiceAsPaidResponse message marks an invoice as paid.
ResponseEnvelope Fields
FieldDescription
ackcommon:AckCode
Acknowledgement code. It is one of the following values:
Su ccess – The operation completed successfully.
Fa ilure – The operation failed.
Su ccessWithWarning – The operation completed successfully;
however, there is a warning message.
Fa ilureWithWarning – The operation failed with a warning message.
10
buildxs:string
Build number. It is used only by PayPal Merchant Technical Support.
correlationIdxs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
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.
timestampxs: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.
Invoicing Service API GuideMay 201299
10
MarkInvoiceAsPaid API Operation
PPFault Message
MarkInvoiceAsPaidResponse Fields
FieldDescription
responseEnvelopecommon:ResponseEnv elope
Common response information, including a timestamp and the response
acknowledgement status.
invoiceIDxs:string
ID of the invoice marked as paid.
invoiceNumberxs:string
Number of the invoice marked as paid.
invoiceURLxs:string
URL location where merchants view the invoice details.
PPFault Message
The PPFaultMessage returns ErrorData and the ResponseE nvelope information to
your application if an error occurs.
100May 2012Invoicing Service API Guide
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.