UpdateInvoice API Operation

Updates an invoice.

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.

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.

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.

Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.

timestamp

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

Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.

UpdateInvoiceResponse Fields

Field

Description

responseEnvelope

common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgment status.