invoicing

Create and Send Invoices

Use the Invoicing API to create and send invoices that bill and accept payments from customers.

Send invoices to customers in the way that you want. PayPal can email your customers directly or you can share an invoice link in an email to your customers. To view and pay the invoice, the customer clicks the invoice link in the email and securely pays with a credit card, debit card, PayPal, or PayPal credit.

Note: Before you can make Invoicing API calls, you must meet the Invoicing Prerequisites.

1. Create draft invoice

In the JSON request body, use the data values from your order to set the invoice request parameters.

Note: The merchant information email must be a confirmed email address on the payment recipient’s PayPal account.

This sample request creates a draft invoice:

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "merchant_info": {
    "email": "merchant@example.com",
    "first_name": "David",
    "last_name": "Larusso",
    "business_name": "Mitchell & Murray",
    "phone": {
      "country_code": "001",
      "national_number": "4085551234"
    }
  },
  "billing_info": [{
    "email": "bill-me@example.com",
    "first_name": "Stephanie",
    "last_name": "Meyers"
  }],
  "items": [{
    "name": "Zoom System wireless headphones",
    "quantity": 2,
    "unit_price": {
      "currency": "USD",
      "value": "120"
    },
    "tax": {
      "name": "Tax",
      "percent": 8
    }
  }],
  "discount": {
    "percent": 1
  },
  "shipping_cost": {
    "amount": {
      "currency": "USD",
      "value": "10"
    }
  },
  "note": "Thank you for your business.",
  "terms": "No refunds after 30 days."
}'

A successful request returns the HTTP 201 Created status code and a JSON response body that shows invoice details. Save the id field value.

The links array contains HATEOAS links that enable you to complete other actions for the invoice:

HATEOAS link Action
{
  "rel": "self",
  "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
  "method": "GET"
}
Shows invoice details
{
  "rel": "send",
  "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX/send",
  "method": "POST"
}
Sends the invoice
{
  "rel": "update",
  "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
  "method": "PUT"
}
Updates the invoice
{
  "rel": "delete",
  "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-FSLW-8GKP-N3QV-QQCX",
  "method": "DELETE"
}
Deletes the invoice

After you create a draft invoice, you must send it to move the invoice from the draft to the payable state.

2. Send invoice

When you send an invoice to your customer, the invoice moves from the draft to the payable state and these actions occur:

  • Both you and your customer receive an email notification.
  • The invoice status updates to SENT.
  • The customer’s view of the invoice includes an online payment button.

To send an invoice, include the invoice id from the create invoice call in the URI of the send request.

Note: You can send an invoice only once.

This sample request sends an invoice to the customer:

curl -v -X POST \
    https://api.sandbox.paypal.com/v1/invoicing/invoices/invoice_id/send?notify_merchant=true?notify_customer=true \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 202 Accepted status code with no JSON response body.

3. Schedule invoice

You can schedule an invoice, by ID, to send it on a future date.

At 07:00 on the invoice date in the preferred time zone of your PayPal account profile, PayPal completes these actions:

  1. Emails an invoice notification to you and your customer.
  2. Updates the invoice status to SENT.
  3. Adds an online payment button to the customer’s view of the invoice.

Note: To change the scheduled date, adjust the invoice date and update invoice. To send the invoice immediately, update the invoice date to today or to a date in the past.

This sample request schedules an invoice:

curl -v -X \
    POST https://api.sandbox.paypal.com/v1/invoicing/invoices/invoice_id/schedule \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 202 Accepted status code and a JSON response body with a link to the invoice:

{
  "links": [{
    "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
    "rel": "self",
    "method": "GET"
  }]
}

4. Generate QR code

You can generate a quick response (QR) code, or a Base64-encoded PNG image, for an invoice:

  1. To generate the QR code, include the invoice ID in the generate QR code request URL.
  2. You can add the QR code to a paper or PDF invoice.
  3. When a customer uses a mobile device to scan the QR code, he or she is redirected to the PayPal mobile payment flow to view the invoice and pay online with PayPal or a credit card.

Note: Before you get a QR code, you must create a draft invoice and send it to move it from a draft to payable state.

If you do not want PayPal to email the invoice notification to your customer, set the notify_customer query parameter to false in the send invoice request. This query parameter updates the invoice status to UNPAID and does not send the email notification.

This sample request generates a QR code:

curl -v -X GET \
    https://api.sandbox.paypal.com/v1/invoicing/invoices/invoice_id/qr-code \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the QR code as a Base64-encoded image.

For example:

{
  "image": "iVBORw0KGgoAA......XUDM"
}

Note: When you use a PayPal SDK, the generate QR call returns a long string. Use your preferred programming language to convert this Base64-encoded value to an image that you can display on your site to your customers.

5. Send invoice reminder

To remind a customer to pay an invoice, include the invoice ID in the URI of the request and include the reminder details in the JSON request body. The reminder details can include the subject and note of the reminder, a flag that indicates whether to send a copy of the email to the merchant, and one or more CC: email addresses. By default, the reminder includes a generic subject and note and sends a copy of the email to the merchant.

This sample request sends an invoice reminder:

curl -v -X POST \
  https://api.sandbox.paypal.com/v1/invoicing/invoices/invoice_id/remind \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "subject": "Past due",
  "note": "Please pay soon.",
  "send_to_merchant": true,
  "cc_emails": ["cc-email@example.com"]
}'

A successful request returns the HTTP 202 Accepted status code with no JSON response body.

Next

Continue to Process Invoices.

Feedback