UpdateInvoice API Operation

API

Last updated: Aug 15th, 7:26am

Updates an invoice.

Example

This example sends an invoice using UpdateInvoice. If the invoice was not previously sent, it continues to be a draft. If the invoice was previously sent, it is resent. 

    1curl https://sandbox.svcs.paypal.com/Invoice/UpdateInvoice
    2-s
    3--insecure
    4-H "X-PAYPAL-SECURITY-USERID: "
    5-H "X-PAYPAL-SECURITY-PASSWORD: "
    6-H "X-PAYPAL-SECURITY-SIGNATURE: "
    7-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV"
    8-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV"
    9-H "X-PAYPAL-APPLICATION-ID: " 
    10-d requestEnvelope.errorLanguage=en_US
    11-d invoice.merchantEmail=merchant%40domain.com
    12-d invoice.payerEmail=jbui-us-business2%40paypal.com
    13-d invoice.currencyCode=USD
    14-d invoice.itemList.item(0).name=Banana+Leaf+--+001
    15-d invoice.itemList.item(0).description=Banana+Leaf
    16-d invoice.itemList.item(0).quantity=3
    17-d invoice.itemList.item(0).unitPrice=1
    18-d invoice.itemList.item(0).taxName=Tax1
    19-d invoice.itemList.item(0).taxRate=10.25
    20-d invoice.paymentTerms=Net10
    21-d invoice.logoUrl=https%3A%2F%2Fexample.com%2FYour_logo.jpg

    UpdateInvoiceRequest Message

    Use the UpdateInvoiceRequest message to update an invoice.

    RequestEnvelope Fields

    Field Description
    detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application pertaining to a particular data component. The detail level is specified as a detail level code, which has all the enumerated values of the detail level for the component. By default, the detail level code is ReturnAll, which provides the maximum level of detail.
    errorLanguage xs:string (Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported.

    UpdateInvoiceRequest Fields

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

    InvoiceType Fields

    Field Description
    merchantEmail xs:string (Required) Merchant email address.
    payerEmail xs:string (Optional) Payer email address. This value is optional if the invoice is in a draft state. However, this value is required for sending an invoice and for updating an invoice that has been sent.
    number xs:string (Optional) Unique identifier for the invoice.
    merchantInfo inv:BusinessInfoType Company information of the merchant company sending the invoice.
    itemList inv:InvoiceItemListType (Optional) List of items included in this invoice. This list is optional if the invoice is in a draft state. However, this list is required for sending an invoice.
    taxCalculatedAfterDiscount xs:boolean (Optional) 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 (Required) Currency used for all invoice item amounts and totals.
    invoiceDate xs:dateTime (Optional) Date on which the invoice is enabled.
    dueDate xs:dateTime (Optional) Date on which the invoice payment is due.
    paymentTerms inv:PaymentTermsType (Optional) 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 is specified in the dueDate field, the value is ignored.
    discountPercent xs:decimal (Optional) 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 (Optional) 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.
    taxInclusive xs:boolean (Optional) 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.

    To specify true or false in the taxInclusive field, please use the following definitions:

    • 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 (Optional) General terms for the invoice. Maximum length: 4000 characters.
    note xs:string (Optional) Note to the payer company. Maximum length: 4000 characters.
    merchantMemo xs:string (Optional) Memo for bookkeeping that is private to the merchant.
    billingInfo inv:BusinessInfoType (Optional) Billing information for the payer.
    shippingInfo inv:BusinessInfoType (Optional) Shipping information for the payer.
    shippingAmount xs:decimal (Optional) Cost of shipping.
    shippingTaxName xs:string (Optional) Name of the applicable tax on shipping cost.
    shippingTaxRate xs:decimal (Optional) Rate of the applicable tax on shipping cost.
    logoURL xs:string (Optional) Complete URL to an external image used as the logo, if any.
    referrerCode xs:string (Optional) Build Notification (BN) code for tracking transactions with a particular partner.

    BusinessInfoType Fields

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

    xs:string (Optional) The language of invoices for a payer who does not have a PayPal account or, a unilateral payer. If you omit 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.

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

    You can specify 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 (Optional) Tax ID of the merchant.
    customValue xs:string (Optional) Custom value to be displayed in the contact information details.
    address common:BaseAddress (Optional) Street address of the company.

    BaseAddress Fields

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

    InvoiceItemType Fields

    Field Description
    item inv:InvoiceItemType (Required) Invoice item.

    InvoiceItemType Fields

    Field Description
    name xs:string (Required) SKU or name of the item. Maximum length: 60 characters.
    description xs:string (Optional) Item description. Maximum length: 1000 characters.
    date xs:dateTime (Optional) Date on which the product or service was provided.
    quantity xs:decimal (Required) Item count. Valid values are 0 to 10000.
    unitPrice xs:decimal (Required) Price of the item, in the currency specified by the invoice.
    discountPercent xs:decimal (Optional) 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 (Optional) 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 (Optional) Name of the applicable tax. Required if taxRate is specified.
    taxRate xs:decimal (Optional) Rate of the applicable tax. Required if taxName is specified.

    UpdateInvoiceResponse Message

    The UpdateInvoiceResponse message contains information returned in response to an UpdateInvoiceRequest message.

    ResponseEnvelope Fields

    Field Description
    ack common:AckCode Acknowledgment code. Value is:
    • Success — The operation completed successfully.
    • Failure — The operation failed.
    • SuccessWithWarning — The operation completed successfully; however, there is a warning message.
    • FailureWithWarning — The operation failed with a warning message.
    build xs:string Build number. It is used only by PayPal Merchant Technical Support.
    correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support.
    timestamp xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.774-07:00

    UpdateInvoiceResponse Fields

    Field Description
    responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgment status.
    invoiceId xs:string ID of the updated invoice.
    invoiceNumber xs:string Invoice number of the updated invoice.
    invoiceURL xs:string URL location where merchants view the updated invoice details.
    totalAmount xs:long The total amount of the invoice.

    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 on which the response was sent, for example: 2012-04-02T22:33:35.774-07:00

    UpdateInvoice 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.
    570045 The number of items exceeds this allowed limit.
    570046 The due date occurs before the invoice date.
    570048 A 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.
    570049 The total amount for the invoice cannot be negative.
    570050 The merchant's PayPal account cannot be the same as the payer's account; merchant and payer email addresses presently link to the same account.
    570051 Invoice cannot have more than 10 different taxes.
    570058 Authentication failed. User account is not confirmed.
    570059 Invoice number is too long.
    570060 The status of the invoice is such that it can no longer be updated.
    571001 The specified invoice ID is invalid because the invoice has already been deleted.
    571009 You cannot send this invoice because payer email is not specified.
    580022 This error code corresponds to validation error messages that deal with errors of supplied parameters.
    580046 An invoice already exists for the merchant with this invoice number.
    580047 Invoice does not exist.
    ReferencePayPal.comPrivacyCookiesSupportLegalContact

    We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies