Templates

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.

When you create an invoice with a template_id, the template is used to pre-populate the invoice's common fields. If you're building your own invoice creation UI and want to prefill the form before sending the create request, retrieve the template and use its template_info in your client.

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.

Method, Endpoint, Description
Method	Endpoint	Description
`POST`	`/v2/invoicing/templates`	Create a new template.
`GET`	`/v2/invoicing/templates`	List 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.

Field, Type, Required, Description
Field	Type	Required	Description
`id`	string	Read-only	The PayPal-generated template ID (`TEMP-XXXXXXXXXXXX`).
`name`	string	Required	A merchant-defined name for the template. Shown in the dashboard and template list.
`default_template`	boolean	Optional	If `true`, this template is used as the default when creating invoices. Only one template can be the default at a time. Default: `false`.
`template_info`	object	Optional	The invoice details are pre-populated by this template. See `template_info` for more information.
`settings`	array	Optional	Display rules that control which fields are shown or hidden on invoices created from this template. See settings for more information.
`unit_of_measure`	string	Optional	The unit of measure for line items. Values: `QUANTITY`, `HOURS`, `AMOUNT`. Default: `QUANTITY`.
`standard_template`	boolean	Read-only	If `true`, this is a PayPal system template and can't be deleted.
`links`	array	Read-only	HATEOAS 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.

Field, Type, Description
Field	Type	Description
`detail`	object	Default invoice detail including `currency_code`, `note`, `terms_and_conditions`, `memo`, `reference`, and `attachments`.
`invoicer`	object	The merchant's business information, including name, address, email, phone, logo URL, and tax ID.
`primary_recipients`	array	Default recipient billing and shipping information.
`items`	array	Default line items with name, quantity, unit amount, tax, and unit of measure.
`configuration`	object	Default invoice configuration including `allow_tip`, `tax_calculated_after_discount`, `tax_inclusive`, and `partial_payment` settings.
`amount`	object	Default 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:

Value, Description
Value	Description
`items.date`	The date column on line items.
`items.description`	The description column on line items.
`items.discount`	The per-item discount field.
`items.tax`	The per-item tax field.
`discount`	The invoice-level discount field.
`shipping`	The shipping charge field.
`custom`	The 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.

Templates API

Method, Endpoint, Description
Method	Endpoint	Description
`POST`	`/v2/invoicing/templates`	Create a new template.
`GET`	`/v2/invoicing/templates`	List 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.

Field, Type, Required, Description
Field	Type	Required	Description
`id`	string	Read-only	The PayPal-generated template ID (`TEMP-XXXXXXXXXXXX`).
`name`	string	Required	A merchant-defined name for the template. Shown in the dashboard and template list.
`default_template`	boolean	Optional	If `true`, this template is used as the default when creating invoices. Only one template can be the default at a time. Default: `false`.
`template_info`	object	Optional	The invoice details are pre-populated by this template. See `template_info` for more information.
`settings`	array	Optional	Display rules that control which fields are shown or hidden on invoices created from this template. See settings for more information.
`unit_of_measure`	string	Optional	The unit of measure for line items. Values: `QUANTITY`, `HOURS`, `AMOUNT`. Default: `QUANTITY`.
`standard_template`	boolean	Read-only	If `true`, this is a PayPal system template and can't be deleted.
`links`	array	Read-only	HATEOAS 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.

Field, Type, Description
Field	Type	Description
`detail`	object	Default invoice detail including `currency_code`, `note`, `terms_and_conditions`, `memo`, `reference`, and `attachments`.
`invoicer`	object	The merchant's business information, including name, address, email, phone, logo URL, and tax ID.
`primary_recipients`	array	Default recipient billing and shipping information.
`items`	array	Default line items with name, quantity, unit amount, tax, and unit of measure.
`configuration`	object	Default invoice configuration including `allow_tip`, `tax_calculated_after_discount`, `tax_inclusive`, and `partial_payment` settings.
`amount`	object	Default amount breakdown including shipping, custom charges, and discount.

settings

Supported field_name values:

Value, Description
Value	Description
`items.date`	The date column on line items.
`items.description`	The description column on line items.
`items.discount`	The per-item discount field.
`items.tax`	The per-item tax field.
`discount`	The invoice-level discount field.
`shipping`	The shipping charge field.
`custom`	The 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.

Templates

Create and manage reusable invoice templates using the PayPal Invoicing API.

Templates API

Template object

template_info

settings

Create a template

Request

Response

Quick start using Invoicing API

Use cases

Reference

On this page

On this page

On this page

Templates

Create and manage reusable invoice templates using the PayPal Invoicing API.

Templates API

Template object

template_info

settings

Create a template

Request

Response

Quick start using Invoicing API

Use cases

Reference

On this page

On this page

Templates

Create and manage reusable invoice templates using the PayPal Invoicing API.

Quick start using Invoicing API

Use cases

Reference

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Templates

Create and manage reusable invoice templates using the PayPal Invoicing API.

Quick start using Invoicing API

Use cases

Reference

On this page

On this page