GetInvoiceDetails API Operation

API

Last updated: Aug 15th, 8:03am

Shows detailed information about an invoice.

Example

This example calls GetInvoiceDetails to show information for an invoice: 

curl https://svcs.sandbox.paypal.com/Invoice/GetInvoiceDetails \ -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.detailLevel=ReturnAll \ -d requestEnvelope.errorLanguage=en_US \ -d invoiceID=INV2-RVY9-UWTW-64HZ-BR9W

GetInvoiceDetailsRequest Message

Use the GetInvoiceDetailsRequest message to get invoice data that includes the list of items and total amount to be charged.

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.

GetInvoiceDetailsRequest Fields

Field Description
invoiceID xs:string (Required) ID of the invoice to retrieve.
requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned.

GetInvoiceDetailsResponse 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. 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.

timestamp

xs:datetime Date when the response was sent, for example: 2012-04-02T22:33:35.774-07:00

GetInvoiceDetailsResponse Fields

Field Description
responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgment status.
invoice inv:InvoiceType Container for information about the invoice.
invoiceDetails inv:InvoiceDetailsType Details about the invoice, including the status and state change dates.
paymentDetails inv:PaymentDetailsType Payment details about the invoice.
refundDetails inv:PaymentRefundDetailsType Invoice refund details.
invoiceURL xs:string URL for viewing the invoice.

InvoiceType Fields

Field Description
merchantEmail xs:string Merchant email address.
payerEmail xs:string Payer email address.
number xs:string Unique identifier for the invoice.
merchantInfo inv:BusinessInfoType Company information of the merchant company sending the invoice.
itemList inv:InvoiceItemListType List of items included in this invoice.
taxCalculatedAfterDiscount xs:boolean Indicates whether tax is calculated before or after a discount. If false (the default), the tax is calculated before a discount. If true, the tax is calculated after a discount.
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.
paymentTerms

inv:PaymentTermsType Terms under which payment is due, specified as one of the following values:

  • DueOnReceipt. Payment is due when the payer receives the invoice.
  • DueOnDateSpecified. Payment is due on the date specified in the invoice.
  • Net10. Payment is due 10 days from the invoice date.
  • Net15. Payment is due 15 days from the invoice date.
  • Net30. Payment is due 30 days from the invoice date.
  • Net45. Payment is due 45 days from the invoice date.
  • NoDueDate. No payment due date is displayed for the invoice; if a value was specified in the dueDate field when the invoice was created or updated, the value is ignored.
discountPercent xs:decimal Discount percent applied at the invoice level (not at the item level). Also see the descriptions of the discount fields in the InvoiceItemType Fields.
discountAmount xs:decimal Invoice-level discount amount, calculated after the item-level discounts. The overall discount on an invoice is equal to the addition of the invoice-level and item-level discounts. Note that if discountPercent is provided, discountAmount is ignored. Also see the descriptions of the discount fields in the InvoiceItemType Fields.
totalItemDiscountAmount xs:decimal Total item-level discount on the invoice. Minimum value: 0. Maximum value: 10000.
taxInclusive xs:boolean Determines whether the item amount is tax inclusive or tax exclusive. An item amount is the unit price multiplied by the quantity. By default, the taxInclusive field is false.

The following definitions apply:

  • Tax exclusive: The stated tax is added on top of the item or shipping amount.
  • Tax inclusive: The item or shipping amount already includes the stated tax.

If the taxInclusive field is true, the tax is calculated as follows:

[Item Amount] - ([Item Amount]/(1+[Tax %])

If the taxInclusive field is false, the tax is calculated as follows:

[Item Amount] * [Tax %]
terms xs:string General terms for the invoice. Maximum length: 4000 characters.
note xs:string Note to the payer company. Maximum length: 4000 characters.
merchantMemo xs:string Memo for bookkeeping that is private to the merchant.
billingInfo inv:BusinessInfoType Billing information for the payer.
shippingInfo inv:BusinessInfoType Shipping information for the payer.
shippingAmount xs:decimal Cost of shipping.
shippingTaxName xs:string Name of the applicable tax on shipping cost.
shippingTaxRate xs:decimal Rate of the applicable tax on shipping cost.
shippingTaxAmount xs:decimal The amount of the shipping tax, at the invoice level. Product of the shipping tax rate multiplied by the shipping amount. Minimum value: 0. Maximum value: 10000.
logoURL xs:string External image URL of the invoice logo, if any.
referrerCode xs:string Build Notification (BN) code for tracking transactions with a particular partner.

InvoiceDetailsType Fields

Field Description
status inv:StatusType Status of the invoice.
totalDiscountAmount xs:decimal A calculated value of the amount of the total discount on the invoice, taking into account item-level and invoice-level discounts. Minimum value: 0. Maximum value: 10000.
totalAmount xs:decimal Total amount of the invoice.
origin inv:OriginType Indicates whether the invoice was created by the website or an API call.
createdDate xs:dateTime Date when the invoice was created.
createdBy xs:string Account that created the invoice.
canceledDate xs:dateTime Date when the invoice was canceled, if canceled.
canceledByActor xs:ActorType Actor who canceled the invoice.
canceledBy xs:string Account that canceled the invoice.
lastUpdatedDate xs:dateTime Date when the invoice was last updated.
lastUpdatedBy xs:string Account that last edited the invoice.
firstSentDate xs:dateTime Date when the invoice was first sent.
lastSentDate xs:dateTime Date when the invoice was last sent.
lastSentBy xs:string Account that last sent the invoice.
paidDate xs:dateTime Date when the invoice was paid, if paid.

InvoiceItemListType Fields

Field Description
item inv:InvoiceItemType Invoice item.

InvoiceItemType Fields

Field Description
name xs:string SKU or name of the item. Maximum length: 60 characters.
description xs:string Item description. Maximum length: 1000 characters.
date xs:dateTime Date on which the product or service was provided.
quantity xs:decimal Item count. Valid values are 0 to 10000.
unitPrice xs:decimal Price of the item, in the currency specified by the invoice.
discountPercent xs:decimal A discount percent applied at the item level (not at the invoice level). Enables separate discounts for individual items on an invoice. This discount is compounded with any discounts specified at the invoice level (see all the discount fields listed under the InvoiceType Fields, above). Minimum value: 0. Maximum value: 100.
discountAmount xs:decimal A discount amount applied at the item level (not at the invoice level). Enables separate discounts for individual items on an invoice. This discount is compounded with any discounts specified at the invoice level (see all the discount fields listed under the InvoiceType Fields, above). If discountPercent is provided at the item level, discountAmount at the item level is ignored. Not greater than the item amount. Minimum value: 0. Maximum value: 10000.
taxName xs:string Name of the applicable tax. Required if taxRate was specified.
taxRate xs:decimal Rate of the applicable tax. Required if taxName was specified.
taxAmount xs:decimal The tax amount on the item (derived from the item.quantity, the item.unitPrice, and the item.taxRate), which can be either included or excluded from the item amount. Minimum value: 0. Maximum value: 10000.
imageUrl xs:string PayPal Here only. Image URL for the item. Minimum value: 0. Maximum value: 4000.

BusinessInfoType Fields

Field Description
firstName xs:string First name of the company contact.
lastName xs:string Last name of the company contact.
businessName xs:string Company business name.
phone xs:string Phone number for contacting the company.
fax xs:string Fax number used by the company.
website xs:string Website used by the company.
language

xs:string (Optional) Contains the language of invoices for a payer who does not have a PayPal account or, a unilateral payer. If you do not specify the language field, a unilateral payer receives invoices in the merchant's language.

If the payer has a PayPal account, this field is ignored and the payer's language is used.

The language field is in the billingInfo container and affects the invoice emails and the payer's invoice view. Maximum length: Five characters.

You can specify one of these values:

  • da_DK. Danish.
  • de_DE. German.
  • en_AU. English (Australia).
  • en_GB. English (U.K.).
  • en_US. English (U.S.).
  • es_ES. Spanish (Modern).
  • es_XC. Spanish (Mexico).
  • fr_CA. French (Canadian).
  • fr_FR. French (France).
  • fr_XC. French.
  • he_IL. Hebrew.
  • id_ID. Indonesian.
  • it_IT. Italian.
  • ja_JP. Japanese.
  • nl_NL. Dutch.
  • no_NO. Norwegian.
  • pl_PL. Polish.
  • pt_BR. Portuguese (Brazilian).
  • pt_PT. Portuguese.
  • ru_RU. Russian.
  • sv_SE. Swedish.
  • th_TH. Thai.
  • zh_CN. Simplified Chinese.
  • zh_HK. Traditional Chinese (Hong Kong).
  • zh_TW. Chinese (Taiwan).
  • zh_XC. Simplified Chinese.
taxId xs:string Tax ID of the merchant.
customValue xs:string Custom value to be displayed in the contact information details.
address common:BaseAddress Street address of the company.

BaseAddress Fields

Field Description
line1 xs:string First line of the address.
line1 xs:string First line of the address.
line2 xs:string Second line of the street address.
line2 xs:string Second line of the street address (store number, mall name).
city xs:string City of the address.
state xs:string State for the address.
postalCode xs:string Postal code of the address.
postalCodeExtension xs:string Extension to the postal code.
countryCode xs:string Country code of the address.
type xs:string Type of address.

PaymentDetailsType Fields

Field Description
viaPayPal xs:boolean Returns True if the invoice was paid by PayPal.
paypalPayment inv:PayPalPaymentDetailsType PayPal payment details about the invoice.
otherPayment inv:OtherPaymentDetailsType Offline payment details about one payment record.
paypalPayments inv:PayPalPaymentDetailsListType Reserved for future use. Contains one or more payment records (transactions). Multiple payment records can be associated with one invoice.

PayPalPaymentDetailsType Fields

Field Description
transactionID xs:string Transaction ID of the PayPal payment.
date xs:dateTime Date when the invoice was paid.
transactionType

inv:PaymentTransactionType Reserved for future use. The type of payment record (transaction). A transactionTypeis one of the following values:

  • Authorization.Reserved for future use.
  • Capture. Reserved for future use.
  • Sale. Applies after a payment was made on the paypal.com web site.

OtherPaymentDetailsType Fields

Field Description
method

inv:PaymentMethodsType Method that marks an invoice as paid when the payer pays offline. The value is one of the following values:

  • BankTransfer. Payment is made by a bank transfer.
  • Cash. Payment is made in cash.
  • Check. Payment is made by check.
  • CreditCard. Payment is made by a credit card.
  • DebitCard. Payment is made by a debit card.
  • Other. Payment is made by a method not specified in this list.
  • PayPal. Payment is made by PayPal.
  • WireTransfer. Payment is made by a wire transfer.
note xs:string Optional note associated with the payment.
date xs:dateTime Date when the invoice was paid.

PayPalPaymentDetailsListType Fields

Field Description
payment inv:PayPalPaymentDetailsType Reserved for future use. Contains transaction information for one transaction (payment record).

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.
timestamp xs:datetime Date when the response was sent, for example: 2012-04-02T22:33:35.774-07:00

GetInvoiceDetails API Errors

Code Message Additional Information
520002 Internal error.
520003 Authentication failed. API credentials are incorrect.
520009 Account is restricted.
550026 Partner 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.
550027 Merchant cannot access or modify an invoice they did not create; an invoice can only be accessed or modified by the party who created it.
570058 Authentication failed. User account is not confirmed.
571001 The specified invoice ID is invalid because the invoice has already been deleted.
580022 This error code corresponds to validation error messages that deal with errors of supplied parameters.
580047 Invoice does not exist.
ReferencePayPal.comPrivacyCookiesSupportLegalContact

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more