Invoicing / Integrate / Create and Manage Templates

Create and Manage Templates


Use templates to store details that you commonly use in all your invoices, such as your business information, item details, and terms and conditions. You can also use custom settings to bill by quantity, hours, or a flat amount and to show a discount field on invoices.

To create templates, you can use the Invoicing API or the web UI.

After you create templates, you can add invoice details and custom settings from the template to an invoice.

You can also use templates in a third-party invoicing application that offers template functionality to merchants. To enable merchants to select from a list of templates, call list templates to list templates with their template IDs. When a merchant selects a template from the list, your app can:

  • Use the template_id to show template details.
  • Use the returned template_data to pre-populate your own Create invoice form, and use the returned settings to show or hide fields as appropriate.

1. Create templates

To create a template, use one of these methods:

  • The web UI through the Create Invoice or Create Template page.
  • The Invoicing API create template call.

Use the web UI to create templates

Step Description
1.

On the Create Invoice or Create Template page, add details that you want to appear on invoices, such as terms and conditions.

You can also customize settings on the invoice. This way, each time that you create an invoice, the form shows only the fields that matter to your business, such as tax, discount, and shipping.
2.

To save your template:

  • On the Create Invoice page, select Save as template beneath the Save as draft option and provide a name for your template.

  • On the Create Template page, click Save template.

Use the API to create templates

In the JSON request body of the create template method, add details that you want to appear on invoices, such as terms and conditions, to the template_data object.

To provide instructions about fields to show or hide on your invoice template, such as tax, discount, or shipping, use the settings array. Each time that you create an invoice, the invoice shows only the fields that matter to your business.

This sample request creates a template that defines merchant information, a standard invoice item, and custom settings that hide the date and custom fields from the invoice:

curl -v -X POST https://api-m.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": {
    "merchant_info": {
      "email": "doctor@example.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"
      }
    },
    "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/00/s/MjA2WDE4NzRYUE5H/p/ZDBlYzMxOTctZDE0Ni00ZmQ0LThkZTgtNGU5YzYyNjg3OTRh/image_109.PNG"
  },
  "settings": [{
    "field_name": "items.date",
    "display_preference": {
      "hidden": true
    }
  }, {
    "field_name": "custom",
    "display_preference": {
      "hidden": true
    }
  }]
}'

A successful request returns the HTTP 200 OK status code and a JSON response body that shows template details:

{
  "template_id": "TEMP-XYZ",
  "name": "Hours Template",
  "default": true,
  "unit_of_measure": "HOURS",
  "template_data": {
    "merchant_info": {
      "email": "doctor@example.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"
      }
    },
    "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/00/s/MjA2WDE4NzRYUE5H/p/ZDBlYzMxOTctZDE0Ni00ZmQ0LThkZTgtNGU5YzYyNjg3OTRh/image_109.PNG"
  },
  "settings": [{
    "field_name": "items.date",
    "display_preference": {
      "hidden": true
    }
  }, {
    "field_name": "custom",
    "display_preference": {
      "hidden": true
    }
  }],
  "links": [{
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
    "rel": "replace",
    "method": "PUT"
  }, {
    "href": "https://api-m.sandbox.paypal.com/v1/invoicing/templates/TEMP-XYZ",
    "rel": "delete",
    "method": "DELETE"
  }]
}

2. Use templates

You can use a template to add invoice details and custom settings to an invoice.

You can also offer template functionality to merchants through a third-party invoicing app.

Add information to invoices

Step Description
1.

On the Create Invoice page, select a template from the My templates drop-down:

Note: Merchants who bill by quantity, a flat amount, or hours can use the PayPal‑provided Quantity, Amount only, and Hours templates.
2.

Enter information for your invoice. Then, complete these actions:

  • To preview the invoice, click Preview.
  • To save the draft invoice, click Save as draft.
  • To send the draft invoice, click Send.

Create third-party invoicing apps

You can offer template functionality to merchants through a third-party invoicing app.

Your app can call list templates to construct a list of templates with template IDs. Merchants can select a template from this list.

To filter which template attributes appear in the list, use the fields query parameter. To return only the template name, ID, and default attributes, set fields to none. To return all fields, set fields to all. Default is all.

When a merchant selects a template from the list, your app can:

  1. Use the template_id of the selected template to show template details.
  2. Use the template_data from the show template details call to populate your own Create invoice form, and use the returned settings to show or hide fields as appropriate.

Note: When you add a template_id to an invoice, it does not automatically import information from the template.

3. Manage templates

To list templates, view template details, and delete templates, use the Template Settings page.

To re-create the Template Settings page in an app, call these methods:

Next

Continue to Test Invoices.