openapi: 3.0.3
info:
title: Paypal Subscriptions Authorizations Templates API
description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
version: '1.6'
contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
description: PayPal Live Environment
tags:
- name: Templates
description: Use the `/templates` resource to create, list, show details for, update, and delete invoice templates. Use the `/templates` resource when you create a third-party invoicing application. For instance, a business can create a template with predefined invoice data. Later, the business can select the template to populate the invoice data.<blockquote><strong>Note:</strong> To upload a logo to display on an invoice, you can use the <strong>Template Settings</strong> dashboard to <a href="https://www.paypal.com/invoice/settings/templates">create a template</a>. When you create an invoice, you can use the URI for that logo.</blockquote>
paths:
/v2/invoicing/templates:
get:
summary: Paypal List templates
description: Lists merchant-created templates with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.<br/>The user can select which values to show in the business information section of their template.
operationId: templates.list
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that lists invoices.
content:
application/json:
schema:
$ref: '#/components/schemas/templates'
multipart/mixed:
schema:
$ref: '#/components/schemas/templates'
'400':
description: Invalid request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/400'
multipart/mixed:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/400'
'403':
description: Authorization Error.
content:
application/json:
schema:
$ref: '#/components/schemas/error_403'
multipart/mixed:
schema:
$ref: '#/components/schemas/error_403'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/fields'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/page_size'
security:
- Oauth2:
- https://uri.paypal.com/services/invoicing/invoices/read
tags:
- Templates
post:
summary: Paypal Create template
description: Creates an invoice template. You can use details from this template to create an invoice. You can create up to 50 templates.<blockquote><strong>Note:</strong> Every merchant starts with three PayPal system templates that are optimized for the unit type billed. The template includes `Quantity`, `Hours`, and `Amount`.</blockquote>
operationId: templates.create
responses:
'201':
description: A successful request returns the HTTP `201 Created` status code. A JSON response body that shows template details is returned if you set <code>prefer=return=representation</code>.
content:
application/json:
schema:
$ref: '#/components/schemas/template'
multipart/mixed:
schema:
$ref: '#/components/schemas/template'
'400':
description: Invalid request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/templates.create-400'
multipart/mixed:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/templates.create-400'
'422':
description: Unprocessable Entity.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/templates.create-422'
multipart/mixed:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/templates.create-422'
default:
$ref: '#/components/responses/default'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/template'
required: true
security:
- Oauth2:
- https://uri.paypal.com/services/invoicing/invoices/readwrite
tags:
- Templates
/v2/invoicing/templates/{template_id}:
get:
summary: Paypal Show template details
description: Shows details for a template, by ID.
operationId: templates.get
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code and a JSON response body that shows template details.
content:
application/json:
schema:
$ref: '#/components/schemas/template'
examples:
'0':
$ref: '#/components/examples/template'
'1':
$ref: '#/components/examples/template_1'
multipart/mixed:
schema:
$ref: '#/components/schemas/template'
'403':
description: Authorization Error.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/templates.get-403'
multipart/mixed:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/templates.get-403'
'404':
description: Resource Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/error_404'
multipart/mixed:
schema:
$ref: '#/components/schemas/error_404'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/template_id'
security:
- Oauth2:
- https://uri.paypal.com/services/invoicing/invoices/read
tags:
- Templates
put:
summary: Paypal Fully update template
description: Fully updates a template, by ID. In the JSON request body, include a complete `template` object. This call does not support partial updates.
operationId: templates.update
responses:
'200':
description: A successful request returns the HTTP `200 OK` status code. A JSON response body that shows template details is returned if you set <code>prefer=return=representation</code>.
content:
application/json:
schema:
$ref: '#/components/schemas/template'
'400':
description: Invalid request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/templates.update-400'
'403':
description: Authorization Error.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/403'
'404':
description: Resource Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/error_404'
'422':
description: Unprocessable Entity.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/templates.update-422'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/template_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/template'
description: A representation of changes to make in the template.
required: true
security:
- Oauth2:
- https://uri.paypal.com/services/invoicing/invoices/readwrite
tags:
- Templates
delete:
summary: Paypal Delete template
description: Deletes a template, by ID.
operationId: templates.delete
responses:
'204':
description: A successful request returns the HTTP `204 No Content` status code with no JSON response body.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/error_400'
multipart/mixed:
schema:
$ref: '#/components/schemas/error_400'
'403':
description: Authorization Error.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/templates.delete-403'
multipart/mixed:
schema:
allOf:
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/templates.delete-403'
'404':
description: Resource Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/error_404'
multipart/mixed:
schema:
$ref: '#/components/schemas/error_404'
'422':
description: Unprocessable Entity.
content:
application/json:
schema:
$ref: '#/components/schemas/error_422'
multipart/mixed:
schema:
$ref: '#/components/schemas/error_422'
default:
$ref: '#/components/responses/default'
parameters:
- $ref: '#/components/parameters/template_id'
security:
- Oauth2:
- https://uri.paypal.com/services/invoicing/invoices/readwrite
tags:
- Templates
components:
schemas:
file_reference:
type: object
title: File Reference
description: The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or other custom store.
properties:
id:
type: string
description: The ID of the referenced file.
minLength: 1
maxLength: 255
reference_url:
type: string
description: The reference URL for the file.
format: uri
minLength: 1
maxLength: 2000
content_type:
type: string
description: The [Internet Assigned Numbers Authority (IANA) media type of the file](https://www.iana.org/assignments/media-types/media-types.xhtml).
create_time:
$ref: '#/components/schemas/date_time'
description: The date and time when the file was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
size:
type: string
description: The size of the file, in bytes.
pattern: ^[0-9]+$
templates.update-400:
properties:
details:
type: array
items:
anyOf:
- title: TEMPLATE_NAME_ALREADY_EXISTS
properties:
issue:
type: string
enum:
- TEMPLATE_NAME_ALREADY_EXISTS
description:
type: string
enum:
- Template name already exists.
- title: INVALID_STRING_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_LENGTH
description:
type: string
enum:
- Template name length should be between 1 and 500.
- title: INVALID_STRING_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_LENGTH
description:
type: string
enum:
- Currency code length should be 3 characters.
- title: INVALID_STRING_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_LENGTH
description:
type: string
enum:
- Value of the field is either too short or too long.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- Value of the field is too long.
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- Value of the field does not conform to the expected format.
error_404:
type: object
title: Not found Error
description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.
properties:
name:
type: string
enum:
- RESOURCE_NOT_FOUND
message:
type: string
enum:
- The specified resource does not exist.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
language:
type: string
description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/).
format: ppaas_common_language_v3
maxLength: 10
minLength: 2
pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$
payment_term:
type: object
title: Payment Term
description: The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.
properties:
term_type:
description: The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
$ref: '#/components/schemas/payment_term_type'
phone_type:
type: string
title: Phone Type
description: The phone type.
enum:
- FAX
- HOME
- MOBILE
- OTHER
- PAGER
'403':
properties:
details:
type: array
items:
anyOf:
- title: PERMISSION_DENIED
properties:
issue:
type: string
enum:
- PERMISSION_DENIED
description:
type: string
enum:
- The requested invoice is not associated with the requested user.
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
required:
- href
- rel
properties:
href:
type: string
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel:
type: string
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
method:
type: string
description: The HTTP method required to make the related call.
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
item:
type: object
title: Invoice Item
description: An array of invoice line item information. The maximum items for an invoice is `100`.
properties:
id:
type: string
description: The ID of the invoice line item.
readOnly: true
maxLength: 22
name:
type: string
description: The item name for the invoice line item.
maxLength: 200
description:
type: string
description: The item description for the invoice line item.
maxLength: 1000
quantity:
type: string
maxLength: 14
minLength: 0
description: The quantity of the item that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places.
unit_amount:
$ref: '#/components/schemas/money'
description: The unit price of the item. This does not include tax and discount. Value is from `-1000000` to `1000000`. Supports up to two decimal places.
tax:
$ref: '#/components/schemas/tax'
description: The tax associated with the item. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places.
item_date:
$ref: '#/components/schemas/date_no_time'
description: The date when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.
discount:
$ref: '#/components/schemas/discount'
description: Discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
unit_of_measure:
description: The unit of measure for the invoiced item. For `AMOUNT` the `unit_amount` and `quantity` are not shown on the invoice.<blockquote><strong>Note:</strong> If your specify different `unit_of_measure` values for the same invoice, the invoice uses the first value.</blockquote>
$ref: '#/components/schemas/unit_of_measure'
required:
- name
- quantity
- unit_amount
payment_term_type:
type: string
title: Payment Term Type
description: The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
enum:
- DUE_ON_RECEIPT
- DUE_ON_DATE_SPECIFIED
- NET_10
- NET_15
- NET_30
- NET_45
- NET_60
- NET_90
- NO_DUE_DATE
date_no_time:
type: string
description: The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
format: ppaas_date_notime_v2
minLength: 10
maxLength: 10
pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$
aggregated_discount:
type: object
title: Aggregated Discount
description: The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent.
properties:
invoice_discount:
$ref: '#/components/schemas/discount'
description: The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
item_discount:
$ref: '#/components/schemas/money'
description: The discount as a percent or amount at item level. The item discount amount is subtracted from each item amount.
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
error_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
template_item_field:
type: string
title: Template Item Field
description: The field names for the invoice line items in the template.
enum:
- ITEMS_QUANTITY
- ITEMS_DESCRIPTION
- ITEMS_DATE
- ITEMS_DISCOUNT
- ITEMS_TAX
templates.update-422:
properties:
details:
type: array
items:
anyOf:
- title: CANNOT_CANCEL_DRAFT_INVOICE
properties:
issue:
type: string
enum:
- CANNOT_CANCEL_DRAFT_INVOICE
description:
type: string
enum:
- Cannot cancel a draft invoice.
template_display_preference:
type: object
title: Template Display Preference
description: The template display preference.
properties:
hidden:
type: boolean
description: Indicates whether to show or hide this field.
default: false
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
default: body
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
name:
type: object
title: Name
description: The name of the party.
properties:
prefix:
type: string
description: The prefix, or title, to the party's name.
maxLength: 140
given_name:
type: string
description: When the party is a person, the party's given, or first, name.
maxLength: 140
surname:
type: string
description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
maxLength: 140
middle_name:
type: string
description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
maxLength: 140
suffix:
type: string
description: The suffix for the party's name.
maxLength: 140
alternate_full_name:
type: string
description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
maxLength: 300
full_name:
type: string
description: When the party is a person, the party's full name.
maxLength: 300
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
type: string
minLength: 0
maxLength: 20000
pattern: ^.*$
rel:
description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
type: string
minLength: 0
maxLength: 100
pattern: ^.*$
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 7
pattern: ^[A-Z]*$
enum:
- CONNECT
- DELETE
- GET
- HEAD
- OPTIONS
- PATCH
- POST
- PUT
phone_detail:
type: object
title: Phone Detail
description: The phone details. Includes the phone number and type.
required:
- phone_type
allOf:
- $ref: '#/components/schemas/phone'
- properties:
phone_type:
$ref: '#/components/schemas/phone_type'
templates.delete-403:
properties:
details:
type: array
items:
anyOf:
- title: PERMISSION_DENIED
properties:
issue:
type: string
enum:
- PERMISSION_DENIED
description:
type: string
enum:
- The requested template is not associated with the requested user.
- title: CANNOT_DELETE_GLOBAL_TEMPLATE
properties:
issue:
type: string
enum:
- CANNOT_DELETE_GLOBAL_TEMPLATE
description:
type: string
enum:
- Global templates cannot be deleted.
template_subtotal_setting:
type: object
title: Template Subtotal Setting
description: The template subtotal setting. Includes the field name and display preference.
properties:
field_name:
description: The field name in `template_data` for which to map corresponding display preferences.
$ref: '#/components/schemas/template_subtotal_field'
display_preference:
description: The display preference.
$ref: '#/components/schemas/template_display_preference'
phone:
type: object
title: Phone
description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).
properties:
country_code:
type: string
description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
minLength: 1
maxLength: 3
pattern: ^[0-9]{1,3}?$
national_number:
type: string
description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number con
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-templates-api-openapi.yml