invoicing

Create 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, merchants can use the web UI, or you can use the API. These instructions explain how to create templates with the API.

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

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

Sample request

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.sandbox.paypal.com/v2/invoicing/templates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
    "name":"Yoga Mat and Shirt",
    "default_template": true,
            "template_info": {
                "configuration": {
                    "tax_calculated_after_discount": true,
                    "tax_inclusive": false,
                    "allow_tip": true,
                    "partial_payment": {
                        "allow_partial_payment": true,
                        "minimum_amount_due": {
                            "currency_code": "USD",
                            "value": "20.00"
                        }
                    }
                },
                "detail": {
                    "reference": "deal-ref",
                    "note": "Thank you for your business.",
                    "currency_code": "USD",
                    "terms_and_conditions": "No refunds after 30 days.",
                    "memo": "This is a long contract",
                    "attachments": [
                        {
                            "id": "Screen Shot 2018-11-23 at 16.45.01.png",
                            "reference_url": "https://api.paypal.com/invoice/payerView/attachments/RkG9ggQbd4Mwm1tYdcF6uuixfFTFq32bBdbE1VbtQLdKSoS2ZOYpfjw9gPp7eTrZmVaFaDWzixHXm-OXWHbmigHigHzURDxJs8IIKqcqP8jawnBEZcraEAPVMULxf5iTyOSpAUc2ugW0PWdwDbM6mg-guFAUyj3Z98H7htWNjQY95jb9heOlcSXUe.sbDUR9smAszzzJoA1NXT6rEEegwQ&version=1&sig=JNODB0xEayW8txMQm6ZsIwDnd4eh3hd6ijiRLi4ipHE"
                        }
                    ],
                    "payment_term": {
                        "term_type": "NET_10"
                    }
                },
                "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": "www.test.com",
                    "tax_id": "ABcNkWSfb5ICTt73nD3QON1fnnpgNKBy-Jb5SeuGj185MNNw6g",
                    "logo_url": "https://example.com/logo.PNG",
                    "additional_notes": "2-4"
                },
                "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": "bill-me@example.com",
                            "phones": [
                                {
                                    "country_code": "001",
                                    "national_number": "4884551234",
                                    "phone_type": "MOBILE"
                                }
                            ],
                            "additional_info": "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"
                            }
                        }
                    }
                ],
                "additional_recipients": [
                    "inform-me@example.com"
                ],
                "items": [
                    {
                        "name": "Yoga Mat",
                        "description": "PVC mat to practice yoga",
                        "quantity": "1",
                        "unit_amount": {
                            "currency_code": "USD",
                            "value": "50.00"
                        },
                        "tax": {
                            "name": "Sales Tax",
                            "percent": "7.25"
                        },
                        "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"
                        },
                        "unit_of_measure": "QUANTITY"
                    }
                ],
                "amount": {
                    "currency_code": "USD",
                    "value": "84.36",
                    "breakdown": {
                        "custom": {
                            "label": "Shipping Charges",
                            "amount": {
                                "currency_code": "USD",
                                "value": "10.00"
                            }
                        },
                        "shipping": {
                            "amount": {
                                "currency_code": "USD",
                                "value": "10.00"
                            },
                            "tax": {
                                "name": "Sales Tax",
                                "percent": "7.25"
                            }
                        }
                    }
                }
            },
            "settings": {
                "template_item_settings": [
                    {
                        "field_name": "items.date",
                        "display_preference": {
                            "hidden": true
                        }
                    },
                    {
                        "field_name": "items.discount",
                        "display_preference": {
                            "hidden": false
                        }
                    },
                    {
                        "field_name": "items.tax",
                        "display_preference": {
                            "hidden": false
                        }
                    },
                    {
                        "field_name": "items.description",
                        "display_preference": {
                            "hidden": false
                        }
                    },
                    {
                        "field_name": "items.quantity",
                        "display_preference": {
                            "hidden": true
                        }
                    }
                ],
                "template_subtotal_settings": [
                    {
                        "field_name": "custom",
                        "display_preference": {
                            "hidden": false
                        }
                    },
                    {
                        "field_name": "discount",
                        "display_preference": {
                            "hidden": false
                        }
                    },
                    {
                        "field_name": "shipping",
                        "display_preference": {
                            "hidden": false
                        }
                    }
                ]
            },
            "unit_of_measure": "QUANTITY",
            "standard_template": false
        }

Sample response

A successful request returns the HTTP 201 Created status code and a JSON response body with the template ID:

{
    "rel": "self",
    "href": "https://api.sandbox.paypal.com/v2/invoicing/templates/TEMP-4S7973887L4810214",
    "method": "GET"
}

Next

Continue to Use Templates.