CreateAndSendInvoice API Operation

API

Last updated: Aug 15th, 5:58am

Important: The Adaptive Platform API is not available for new integrations. PayPal provides this documentation to support existing integrations. If you're starting an integration, we recommend our latest solutions.

Creates an invoice and sends it to a customer.

Example

This example creates and sends an invoice using CreateAndSendInvoice.

1curl https://svcs.sandbox.paypal.com/Invoice/CreateAndSendInvoice \
2  -s \
3  --insecure \
4  -H "X-PAYPAL-SECURITY-USERID: <var>Your_API_username</var>" \
5  -H "X-PAYPAL-SECURITY-PASSWORD: <var>Your_API_password</var>" \
6  -H "X-PAYPAL-SECURITY-SIGNATURE: <var>Your_API_signature</var>" \
7  -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \
8  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \
9  -H "X-PAYPAL-APPLICATION-ID: <var>Your_AppID</var>"  \
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=1 \
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

CreateAndSendInvoiceRequest Message

Use the CreateAndSendInvoiceRequest message to create a new invoice and send it to a customer. 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.

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.

CreateAndSendInvoiceRequest Fields

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

InvoiceType Fields

Field	Description
`merchantEmail`	`xs:string` (Required) Merchant email address.
`payerEmail`	`xs:string` (Required) Payer email address, required for sending an invoice.
`number`	`xs:string` (Optional) Unique identifier for the invoice.
`merchantInfo`	`inv:BusinessInfoType` Company information of the merchant company sending the invoice.
`itemList`	`inv:InvoiceItemListType` (Required) List of items included in this invoice. 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, 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 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` (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.

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

CreateAndSendInvoiceResponse Message

The CreateAndSendInvoiceResponse 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

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.

CreateAndSendInvoiceResponse Fields

Field	Description
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.
`invoiceID`	`xs:string` ID of the created invoice. Maximum length: 24 characters.
`invoiceNumber`	`xs:string` Number of the created invoice.
`invoiceURL`	`xs:string` URL location where merchants view the 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 six-digit number that uniquely identifies a particular error.
`exceptionID`	This field is not used.
`message`	`xs:string` A description of the error.
`parameter`	`common:ErrorParameter` Represents contextual information about the error.
`severity`	`common:ErrorSeverity` The severity of the error encountered. Value is: `Error`. Processing of the request was interrupted. `Warning`. Processing of the request was completed.
`subdomain`	This field is not used.

ResponseEnvelope Fields

Field	Description
`ack`	`common:AckCode` Acknowledgment code. Value is: `Success`. The operation completed successfully. `Failure`. The operation failed. `SuccessWithWarning`. The operation completed successfully; however, there is a warning message. `FailureWithWarning`. The operation failed with a warning message.
`build`	`xs:string` Build number. It is used only by PayPal Merchant Technical Support.
`correlationId`	`xs:string` Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support. Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
`timestamp`	`xs:datetime` Date on which the response was sent, for example: `2012-04-02T22:33:35.774-07:00` Note: You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.

CreateAndSendInvoice API Errors

Code	Message
520002	Internal error.
520003	Authentication failed. API credentials are incorrect.
520009	Account is restricted.
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.
570054	Invalid token.
570058	Authentication failed. User account is not confirmed.
571009	You cannot send this invoice because payer email is not specified.
570059	Invoice number is too long.
580022	This error code corresponds to validation error messages that deal with errors of supplied parameters.
580045	Merchant does not have a PayPal account associated with this email address.
580046	An invoice already exists for the merchant with this invoice number.