Integrate Invoicing

DocsCurrentLast updated: September 30th 2021, @ 5:56:39 pm


Know before you code

  • Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:

    • Your personal and business sandbox accounts
    • Your access token
  • Use your sandbox business email address as the address for the Invoicer API object.
  • This integration uses the Invoicing REST API.

1. Create draft

To draft an invoice, copy the following code and modify it.

Sample request

This sample request creates an invoice:

  • From sender David Larusso (including address, email address, and phone number)
  • To recipient Stephanie Meyers (including address, email address, and phone number)
  • For one $50 yoga mat (including sales tax)
  • For one $10 t-shirt (including sales tax)
  • With $20 minimum partial payments enabled
  • With optional tip
  • With $10 packing charges and $10 shipping charges (including sales tax)
  • With a 5% invoice discount

API endpoint used: Create draft invoice

curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
  "detail": {
    "invoice_number": "123",
    "reference": "deal-ref",
    "invoice_date": "2020-11-12",
    "currency_code": "USD",
    "note": "Thank you for your business.",
    "term": "No refunds after 30 days.",
    "memo": "This is a long contract",
    "payment_term": {
      "term_type": "NET_10",
      "due_date": "2020-11-22"
    }
  },
  "invoicer": {
    "name": {
      "given_name": "David",
      "surname": "Larusso"
    },
    "address": {
      "address_line_1": "1234 First Street",
      "address_line_2": "337673 Hillside Court",
      "admin_area_2": "Anytown",
      "admin_area_1": "CA",
      "postal_code": "98765",
      "country_code": "US"
    },
    "email_address": "<merchant@example.com>",
    "phones": [
      {
        "country_code": "001",
        "national_number": "4085551234",
        "phone_type": "MOBILE"
      }
    ],
    "website": "https://example.com",
    "tax_id": "XX-XXXXXXX",
    "logo_url": "https://example.com/logo.PNG",
    "additional_notes": "example note"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": "<bill-me@example.com>",
        "phones": [
          {
            "country_code": "001",
            "national_number": "4884551234",
            "phone_type": "HOME"
          }
        ],
        "additional_info_value": "add-info"
      },
      "shipping_info": {
        "name": {
          "given_name": "Stephanie",
          "surname": "Meyers"
        },
        "address": {
          "address_line_1": "1234 Main Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        }
      }
    }
  ],
  "items": [
    {
      "name": "Yoga Mat",
      "description": "Elastic mat to practice yoga.",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "50.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25"
      },
      "discount": {
        "percent": "5"
      },
      "unit_of_measure": "QUANTITY"
    },
    {
      "name": "Yoga t-shirt",
      "quantity": "1",
      "unit_amount": {
        "currency_code": "USD",
        "value": "10.00"
      },
      "tax": {
        "name": "Sales Tax",
        "percent": "7.25"
      },
      "discount": {
        "amount": {
          "currency_code": "USD",
          "value": "5.00"
        }
      },
      "unit_of_measure": "QUANTITY"
    }
  ],
  "configuration": {
    "partial_payment": {
      "allow_partial_payment": true,
      "minimum_amount_due": {
        "currency_code": "USD",
        "value": "20.00"
      }
    },
    "allow_tip": true,
    "tax_calculated_after_discount": true,
    "tax_inclusive": false,
    "template_id": ""
  },
  "amount": {
    "breakdown": {
      "custom": {
        "label": "Packing Charges",
        "amount": {
          "currency_code": "USD",
          "value": "10.00"
        }
      },
      "shipping": {
        "amount": {
          "currency_code": "USD",
          "value": "10.00"
        },
        "tax": {
          "name": "Sales Tax",
          "percent": "7.25"
        }
      },
      "discount": {
        "invoice_discount": {
          "percent": "5"
        }
      }
    }
  }
}'

Modify code

After you copy the code in the sample request, modify the following:

  • Change Access-Token to your access token.
  • Change <merchant@example.com> in invoicer: email_address to your sandbox business account email address. When you go live, use the email address associated with your PayPal merchant account.
  • Change invoice_date and due_date to reflect the current or a future date.
  • Optional: Use the details from your order to set other invoice request parameters to populate the details of the invoice.

Step result

A successful request returns the following:

  • An invoice in your sandbox business account in Draft status. See this status by logging into your sandbox business account.
  • A return status code of HTTP 201 Created.
  • A JSON response body that has an ID of the invoice. In the sample response, the ID is INV2-W44B-KRGF-JM6R-26VU.

Use this ID to complete other REST API actions, such as editing or deleting the invoice and sending payment reminders.

Sample response

{
    "rel": "self",
    "href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
    "method": "GET"
}

2. Send

To send the invoice, copy the following code and modify it.

Sample request

API endpoint used: Send invoice

curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU /send \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
  "send_to_invoicer": true
}'

Modify code

After you copy the code in the sample request, modify the following:

  • Change Access-Token to your access token.
  • Change the sample invoice ID, INV2-W44B-KRGF-JM6R-26VU, to the invoice ID that was returned when you created the invoice.

Step result

A successful request returns the following:

  • A return status code of HTTP 200 OK.
  • A JSON response body with information about the invoice.
  • The invoice status in the merchant’s PayPal account moves to Unpaid (Sent).
  • If you set email notifications in the request body, the emails are sent.

Tip: PayPal automatically records payments made in the invoice using the Pay Now button. If you accept payments offline, such as a check or a wire transfer, manually record the payment.

Sample response

{
    "rel": "self",
    "href": "https://api-m.sandbox.paypal.com/v2/invoicing/invoices/INV2-W44B-KRGF-JM6R-26VU",
    "method": "GET"
}

Next

Customize your Invoicing integration