Invoicing overview

Use the REST Invoicing API to create draft invoices and send and manage invoices.

Note: You can optionally create an invoice template. Then, when you create an invoice from a template, the invoice is populated with the predefined data that the source template contains.

When you send an invoice, the invoice moves from draft to payable state and PayPal emails a link to the invoice on the PayPal website to the customer. The customer can view the invoice on the PayPal website and pay with PayPal, a debit card, or a credit card. Or, you can record off-line payments, such as a check.

You can also use the Invoicing API to:

  • Manage templates
  • Manage invoices and payments

Integration steps

To use the REST Invoicing API:

1. Required Meet the prerequisites.
2. Optional Create an invoice template.
3. Required Your app creates a draft invoice for a customer. Create the invoice directly or from a template.
4. Required Your app sends an invoice to the customer.
5. Optional Your app shows invoice details to the customer.
6. Optional Manage payments.
7. Optional Manage invoices.
8. Optional Manage templates.

Prerequisites

To get started, create a REST API app. After you make your first call to the REST API, review the Invoicing API reference.

To call the Invoicing API on behalf of a merchant, you must obtain third-party permissions:

  1. Set up Log In with PayPal so that the merchant can authorize you. To do so, get the Invoicing scope. Then, Integrate Log In with PayPal.

  2. The merchant uses your app to Log In with PayPal and authorizes you.

  3. After you are authorized, you can call any Invoicing API on behalf of the merchant.

Create an invoice template

You can optionally create an invoice template. When you create an invoice from a template, the invoice is populated with the predefined data that the source template contains.

Note: You can use the Template Settings dashboard instead of the API to create an invoice template.

To create an invoice template, specify request parameters in the JSON request body.

This example request creates the Hours Template template with an Hours unit of measure and sets the template as the default merchant template:

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/templates/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
    "items": [{
      "name": "Nutri Bullet",
      "quantity": 1,
      "unit_price": {
        "currency": "USD",
        "value": "50.00"
      }
    }],
    "merchant_info": {
      "email": "jaypatel512-facilitator@hotmail.com"
    },
    "tax_calculated_after_discount": false,
    "tax_inclusive": false,
    "note": "Thank you for your business.",
    "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [{
    "field_name": "items.date",
    "display_preference": {
      "hidden": true
    }
  }, {
    "field_name": "custom",
    "display_preference": {
      "hidden": true
    }
  }]
}'

The response shows information about the template including the PayPal-generated template ID.

{
  "template_id": "TEMP-XYZ",
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "Hours",
  "template_data": {
    "items": [
      {
        "name": "Nutri Bullet",
        "quantity": 1,
        "unit_price": {
          "currency": "USD",
          "value": "50.00"
        }
      }
    ],
    "tax_calculated_after_discount": false,
    "tax_inclusive": false,
    "note": "Thank you for your business.",
    "logo_url": "https://pics.paypal.com/v1/images/redDot.jpeg"
  },
  "settings": [
    {
      "field_name": "items.date",
      "display_preference": {
        "hidden": true
      }
    },
    {
      "field_name": "custom",
      "display_preference": {
        "hidden": true
      }
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "replace",
      "method": "PUT"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
      "rel": "delete",
      "method": "DELETE"
    }
  ]
}

Next, you can use the template ID from the response to create a draft invoice from this template.

Create a draft invoice

You can create a draft invoice directly or from a template. To create an invoice directly, you must include invoice details including merchant information in the JSON request body. The invoice object must include an items array with line item information.

The following example shows you how to create an invoice directly.

Note: You can also create a draft invoice that is based on an invoice template. This template populates the invoice with predefined data. To create a draft invoice from a template, you must specify these parameters in the JSON request body:

  • template_id. The ID of the template from which to create the invoice.
  • merchant_info. Merchant business information that appears on the invoice.

You can also specify other optional parameters. If you do, these values override any values in the source template.

To create a draft invoice directly, specify request parameters in the JSON request body, as shown here:

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": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "001",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [{
    "email": "example@example.com"
  }],
  "items": [{
    "name": "Sutures",
    "quantity": 100,
    "unit_price": {
      "currency": "USD",
      "value": "5"
    }
  }],
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "payment_term": {
    "term_type": "NET_45"
  },
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "001",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  }
}'

A successful call returns an invoice object that includes the ID of the created invoice:

{
  "id": "INV2-RUVR-ADWQ-H89Y-ABCD",
  "number": "ABCD4971",
  "status": "DRAFT",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141234"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "email@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-02-27 PST",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-04-13 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  }
}

Next, send the invoice. When you send an invoice, it moves from a draft to payable state.

Send an invoice

When you send an invoice, PayPal sends an email to the customer with a link to the invoice on the PayPal site. The customer clicks the link and reviews and pays the invoice.

To send an invoice to a customer, specify the invoice ID in the URI of the request. By default, the notify_merchant query parameter is set to true, which sends the merchant an invoice update notification. To withhold this notification, set this parameter to false.

curl -v -X POST https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-EHNV-LJ5S-A7DZ-V6NJ/send \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer Access-Token"

A successful call returns the HTTP 202 (Accepted) status code. After you send an invoice, it changes from draft to payable state.

Next, you can show invoice details. Your app can display these details to the customer.

Show invoice details

To show details for an invoice, specify the invoice ID in the URI:

curl -v -X GET https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7 \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer Access-Token"

The response shows information about the merchant, line items in the invoice, customer billing and shipping details, and the invoice date and payment details. The response also includes HATEOAS links that you can use to send, delete, or update the invoice:

{
  "id": "INV2-RF6D-L66T-D7H2-CRU7",
  "number": "0002",
  "status": "DRAFT",
  "template_id": "TEMP-XYZ",
  "merchant_info": {
    "email": "ppaas_default@paypal.com",
    "first_name": "Dennis",
    "last_name": "Doctor",
    "business_name": "Medical Professionals, LLC",
    "phone": {
      "country_code": "1",
      "national_number": "5032141716"
    },
    "address": {
      "line1": "1234 Main St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97217",
      "country_code": "US"
    }
  },
  "billing_info": [
    {
      "email": "example@example.com"
    }
  ],
  "shipping_info": {
    "first_name": "Sally",
    "last_name": "Patient",
    "business_name": "Not applicable",
    "phone": {
      "country_code": "1",
      "national_number": "5039871234"
    },
    "address": {
      "line1": "1234 Broad St.",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97216",
      "country_code": "US"
    }
  },
  "items": [
    {
      "name": "Sutures",
      "quantity": 100,
      "unit_price": {
        "currency": "USD",
        "value": "5.00"
      }
    }
  ],
  "invoice_date": "2014-03-24 PDT",
  "payment_term": {
    "term_type": "NET_45",
    "due_date": "2014-05-08 PDT"
  },
  "tax_calculated_after_discount": false,
  "tax_inclusive": false,
  "note": "Medical Invoice 16 Jul, 2013 PST",
  "total_amount": {
    "currency": "USD",
    "value": "500.00"
  },
  "metadata": {
    "created_date": "2014-03-24 12:11:52 PDT"
  },
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7/send",
      "rel": "send",
      "method": "POST"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/invoicing/invoices/INV2-RF6D-L66T-D7H2-CRU7",
      "rel": "update",
      "method": "PUT"
    }
  ]
}

Manage payments

To manage payments, you can mark an invoice as partially or fully paid or refunded. You can also delete an external payment or an external refund from an invoice.

To complete these tasks for payments, use the /invoicing/invoices resource:

Task Description
Mark invoice as paid Marks an invoice as partially or fully paid.
Mark invoice as refunded Marks an invoice as partially or fully refunded.
Delete external payment Deletes an external payment, by ID, from an invoice, by ID.
Delete external refund Deletes an external refund, by ID, from an invoice, by ID.

Manage invoices

To manage invoices, you can generate a QR code for, list, search for, show details for, update, send, and send a reminder for invoices. You can also generate an invoice number, delete draft invoices, and cancel sent invoices.

To complete these tasks for invoices, use the /invoicing/invoices resource:

Task Description
Generate QR code Generates a QR code for an invoice, by ID. The QR code is a PNG image in Base64-encoded format that corresponds to the invoice ID. You can generate a QR code for an invoice and add it to a paper or PDF invoice. When a customer uses their mobile device to scan the QR code, he or she is redirected to the PayPal mobile payment flow where he or she can pay online with PayPal or a credit card. Before you get a QR code, you must create and send the invoice.
List invoices Lists all merchant-created invoices. The list shows the invoices for the merchant who makes the call.
Search for invoices Lists invoices that match search criteria.
Show invoice details Shows invoice details, by ID.
Update invoice Updates an invoice, by ID.
Send invoice Sends an invoice, by ID, to a customer.
Send invoice reminder Sends a reminder for an invoice, by ID, to a customer.
Generate invoice number Generates the next invoice number that is available to the user.
Delete draft invoice Deletes a draft invoice, by ID. Note that this call works for invoices in the draft state only. For invoices that have already been sent, you can cancel the invoice. After you delete a draft invoice, you can no longer use it or show its details. However, you can reuse its invoice number.
Cancel sent invoice Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and Cc: emails.

Manage templates

You can create, list, show details for, update, and delete templates.

To complete these tasks for templates, use the /invoicing/templates resource:

Task Description
Create template Creates a template on which you can base an invoice.
List templates Lists all merchant-created templates. The list shows the emails, addresses, and phone numbers from the merchant profile.
Show template details Shows details for a template, by ID.
Update template Updates a template, by ID. In the JSON request body, pass a complete template object. The update method does not support partial updates.
Delete template Deletes a template, by ID.

Additional information