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:
|
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:
|
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:
- Use the
template_id
of the selected template to show template details. - 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:
- List templates.
- Create template. You can create up to 50 templates.
- Update template.
- Delete template.
- Show template details.
Next
Continue to Test Invoices.