Introduction to the Invoicing Service API

PayPal enables you to create and manage invoices. When you send an invoice, PayPal emails the receipient and allows him or her to pay with PayPal.

The following diagram shows the basic execution flow for creating and sending an invoice:



The circled numbers indicate actions that you take as well as actions taken by PayPal and your customer:

  1. Specify the contents of the invoice in the CreateInvoice request and send the request to the https://svcs.paypal.com/Invoice/CreateInvoice endpoint.
  2. Examine the response and verify that the ACK field contains SUCCESS.
  3. Using the invoice ID in the response, create a SendInvoice request and send it to the https://svcs.paypal.com/Invoice/SendInvoice endpoint.
  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/CreateAndSendInvoice endpoint.
  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:



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.

Note: You must have a valid app ID to use the Invoicing Service API. If you have an existing app ID, you can reuse it. For more information, see Creating and Managing Classic API Credentials.

Creating and Sending Invoices

API Operation Description
CreateInvoice Creates a new invoice.
SendInvoice Sends an invoice to a customer.
CreateAndSendInvoice Creates and sends an invoice, which is equivalent to the combination of the CreateInvoice operation followed by the SendInvoice operation.

Managing Invoices

API Operation Description
DeleteInvoice Deletes an invoice that is in the draft state.
UpdateInvoice Updates an invoice.
GetInvoiceDetails Obtains the contents of an invoice.
CancelInvoice Cancels an invoice.
SearchInvoices Searches for invoices based on specified criteria.
MarkInvoiceAsPaid Marks an invoice as having been paid.
MarkInvoiceAsUnpaid Marks an invoice as unpaid.
MarkInvoiceAsRefunded Marks an invoice as having been refunded.

IPN Variables for Invoicing API Operations

PayPal sends IPN messages for invoice payments and for invoices cancelled by the buyer. For more information about IPN, see the Instant Payment Notification Guide.

Invoice Payments

mc_gross: 37.12
protection_eligibility: Eligible
address_status: confirmed
payer_id: ABF644D44GSPJ
address_street: 5656 South Market Street
payment_date: 15:57:39 Sep 12, 2011 PDT
payment_status: Completed
invoice_id: INV2-VMYW-LQKA-QBGC-6YDE
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@paypal.com
address_country: United States
address_city: San Jose
verify_sign: AFcWxV21C7fd0v3bYYYRCpSSRl31A23x28hwIQCThw2nNi2s8MlV2o10
payer_email: jbui-us-personal1@paypal.com
txn_id: 68H067535A2789915
payment_type: instant
last_name: Ronald
address_state: CA
receiver_email: jbui-us-business1@paypal.com
payment_fee: 1.38
receiver_id: 9N3VVZS28ELHL
txn_type: invoice_payment
mc_currency: USD
residence_country: US
transaction_subject: Send the Reminder Soon.
invoice_number: 0151
payment_gross: 37.12
ipn_track_id: ogo4fwr-n.J7dGNgDiJzqg

Canceled Invoices

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-business1@paypal.com
verify_sign: AiPC9BjkCyDFQXbSkoZcgqH3hpacAAV9zVNI.GLTI1sLOHpeeWp3oMQZ
invoice_id: INV2-UHWN-STXM-65B7-PT4R
ipn_track_id: 2eKZJ-cZftAHzSWbsS7qjQ