Skip to main content
Templates let you save reusable invoice details such as your business information, standard line items, payment terms, and display preferences so you don’t have to repeat them every time you create an invoice. You can create up to 50 templates per merchant account. Every account starts with three PayPal system templates pre-optimized for QUANTITY, HOURS, and AMOUNT billing.

​
Templates API

Templates are managed through five endpoints covering the full create, read, update, and delete lifecycle. Use POST to create a new template, GET to retrieve either a single template by ID or your full list, PUT to fully update an existing template, and DELETE to remove one. All template endpoints are scoped to /v2/invoicing/templates and require a valid Bearer token. For the complete request and response schemas, see the Invoicing API reference.
MethodEndpointDescription
POST/v2/invoicing/templatesCreate a new template.
GET/v2/invoicing/templatesList all templates. Use ?fields=all for full details or ?fields=none for name, ID, and default flag only.
GET/v2/invoicing/templates/{template_id}Show details for a single template. Use @default as the ID to retrieve the current default template.
PUT/v2/invoicing/templates/{template_id}Fully update a template by ID. Doesn’t support partial updates, so you’ll need to include the complete template object.
DELETE/v2/invoicing/templates/{template_id}Delete a template by ID. Returns HTTP 204 No Content. Can’t be used on PayPal system templates where standard_template is true.

​
Template object

The following fields make up the template object.
FieldTypeRequiredDescription
idstringRead-onlyThe PayPal-generated template ID (TEMP-XXXXXXXXXXXX).
namestringRequiredA merchant-defined name for the template. Shown in the dashboard and template list.
default_templatebooleanOptionalIf true, this template is used as the default when creating invoices. Only one template can be the default at a time. Default: false.
template_infoobjectOptionalThe invoice details are pre-populated by this template. See template_info for more information.
settingsarrayOptionalDisplay rules that control which fields are shown or hidden on invoices created from this template. See settings for more information.
unit_of_measurestringOptionalThe unit of measure for line items. Values: QUANTITY, HOURS, AMOUNT. Default: QUANTITY.
standard_templatebooleanRead-onlyIf true, this is a PayPal system template and can’t be deleted.
linksarrayRead-onlyHATEOAS links for available actions on the template, for example, self, delete, replace.

​
template_info

The invoice data stored in the template shares the same structure as the invoice object. See the most commonly used fields.
FieldTypeDescription
detailobjectDefault invoice detail including currency_code, note, terms_and_conditions, memo, reference, and attachments.
invoicerobjectThe merchant’s business information, including name, address, email, phone, logo URL, and tax ID.
primary_recipientsarrayDefault recipient billing and shipping information.
itemsarrayDefault line items with name, quantity, unit amount, tax, and unit of measure.
configurationobjectDefault invoice configuration including allow_tip, tax_calculated_after_discount, tax_inclusive, and partial_payment settings.
amountobjectDefault amount breakdown including shipping, custom charges, and discount.

​
settings

An array of display rules controlling field visibility on invoices created from this template. Each entry contains a field_name and a display_preference object with a single hidden boolean. Set hidden: true to hide the field, or hidden: false to show it. Supported field_name values:
ValueDescription
items.dateThe date column on line items.
items.descriptionThe description column on line items.
items.discountThe per-item discount field.
items.taxThe per-item tax field.
discountThe invoice-level discount field.
shippingThe shipping charge field.
customThe custom charge field, for example, packing fees.

​
Create a template

Creates a new invoice template. A successful request returns HTTP 201 Created and the template object if you set Prefer: return=representation.

​
Request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/invoicing/templates \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "name": "Standard Services Invoice",
    "default_template": true,
    "unit_of_measure": "HOURS",
    "template_info": {
      "detail": {
        "currency_code": "USD",
        "note": "Thank you for your business.",
        "terms_and_conditions": "Payment due within 30 days.",
        "memo": "Internal reference only"
      },
      "invoicer": {
        "name": {
          "given_name": "David",
          "surname": "Larusso"
        },
        "address": {
          "address_line_1": "1234 First Street",
          "admin_area_2": "Anytown",
          "admin_area_1": "CA",
          "postal_code": "98765",
          "country_code": "US"
        },
        "email_address": "merchant@example.com",
        "logo_url": "https://example.com/logo.PNG"
      },
      "items": [
        {
          "name": "Consulting",
          "description": "Hourly consulting services.",
          "quantity": "1",
          "unit_amount": {
            "currency_code": "USD",
            "value": "150.00"
          },
          "tax": {
            "name": "Sales Tax",
            "percent": "7.25"
          },
          "unit_of_measure": "HOURS"
        }
      ],
      "configuration": {
        "tax_calculated_after_discount": true,
        "tax_inclusive": false,
        "allow_tip": false
      }
    },
    "settings": [
      {
        "field_name": "items.date",
        "display_preference": { "hidden": false }
      },
      {
        "field_name": "custom",
        "display_preference": { "hidden": true }
      },
      {
        "field_name": "shipping",
        "display_preference": { "hidden": true }
      }
    ]
  }'

​
Response

{
  "id": "TEMP-19V05281TU309413B",
  "name": "Standard Services Invoice",
  "default_template": true,
  "unit_of_measure": "HOURS",
  "standard_template": false,
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "delete",
      "method": "DELETE"
    },
    {
      "href": "https://api-m.paypal.com/v2/invoicing/templates/TEMP-19V05281TU309413B",
      "rel": "replace",
      "method": "PUT"
    }
  ]
}
Save the returned id to reference this template when listing, updating, or associating it with an invoice through configuration.template_id.

Quick start using Invoicing API

Create and send your first invoice using the PayPal Invoicing API.

Use cases

See how templates fit into common invoicing workflows.

Reference

Explore the full schema for the template object and all other Invoicing API objects.