Invoicing Quick Start

Availability: PayPal supports these Invoicing integrations:

  • Invoicing v2. Valid from April 2019 for new integrations.
  • Invoicing v1. Valid before April 2019. Customers who use Invoicing v1 can access reference and support material in this integration guide. However, PayPal does not update this API with new features and enhancements.

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 set up your development environment.

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-m.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 in the response contains HATEOAS links that enable you to complete other actions for the invoice.

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

Next

Continue to the Integration Options.