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_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.sandbox.paypal.com//v2/invoicing/templates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
    "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"
                        },
                        "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"
                    }
                ],
                "amount": {
                    "currency_code": "USD",
                    "value": "74.21",
                    "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"
                            }
                        },
                        "discount": {
                            "invoice_discount": {
                                "percent": "5"
                            }
                        }
                    }
                }
            },
            "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
        }
    },

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

{
  "id": "TEMP-19V05281TU309413B",
            "name": "reference-temp",
            "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"
                    },
                    "metadata": {
                        "create_time": "2018-12-03T03:38:46z"
                    }
                },
                "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": [
                    {
                        "id": "ITEM-9R873787D1610780X",
                        "name": "Yoga Mat",
                        "description": "new watch",
                        "quantity": "1",
                        "unit_amount": {
                            "currency_code": "USD",
                            "value": "50.00"
                        },
                        "tax": {
                            "id": "TAX-9R873787D1610780X",
                            "name": "Sales Tax",
                            "percent": "7.25",
                            "amount": {
                                "currency_code": "USD",
                                "value": "3.27"
                            }
                        },
                        "discount": {
                            "percent": "5",
                            "amount": {
                                "currency_code": "USD",
                                "value": "2.5"
                            }
                        },
                        "unit_of_measure": "QUANTITY"
                    },
                    {
                        "id": "ITEM-4XD34145EH4061035",
                        "name": "Yoga T Shirt",
                        "quantity": "1",
                        "unit_amount": {
                            "currency_code": "USD",
                            "value": "10.00"
                        },
                        "tax": {
                            "id": "TAX-4XD34145EH4061035",
                            "name": "Sales Tax",
                            "percent": "7.25",
                            "amount": {
                                "currency_code": "USD",
                                "value": "0.34"
                            }
                        },
                        "discount": {
                            "amount": {
                                "currency_code": "USD",
                                "value": "5.00"
                            }
                        },
                        "unit_of_measure": "QUANTITY"
                    }
                ],
                "amount": {
                    "currency_code": "USD",
                    "value": "74.21",
                    "breakdown": {
                        "item_total": {
                            "currency_code": "USD",
                            "value": "60.00"
                        },
                        "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",
                                "amount": {
                                    "currency_code": "USD",
                                    "value": "0.73"
                                }
                            }
                        },
                        "discount": {
                            "item_discount": {
                                "currency_code": "USD",
                                "value": "-7.50"
                            },
                            "invoice_discount": {
                                "percent": "5",
                                "amount": {
                                    "currency_code": "USD",
                                    "value": "-2.63"
                                }
                            }
                        },
                        "tax_total": {
                            "currency_code": "USD",
                            "value": "4.34"
                        }
                    }
                }
            },
            "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,
            "links": [
                {
                    "href": "https://api.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
                    "rel": "self",
                    "method": "GET"
                },
                {
                    "href": "https://api.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
                    "rel": "delete",
                    "method": "DELETE"
                },
                {
                    "href": "https://api.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
                    "rel": "replace",
                    "method": "PUT"
                }
            ]
        }
    }
}

Next

Continue to Use Templates.

Feedback