> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # List templates > Lists merchant-created templates with associated details. The associated details include the emails, addresses, and phone numbers from the user's PayPal profile.
The user can select which values to show in the business information section of their template. ## OpenAPI ````yaml /api-reference/invoicing_v2.json get /v2/invoicing/templates openapi: 3.0.3 info: title: Invoices description: >- Use the Invoicing API to create, send, and manage invoices. You can also use the API or webhooks to track invoice payments. When you send an invoice to a customer, the invoice moves from draft to payable state. PayPal then emails the customer a link to the invoice on the PayPal website. Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card. For more information, see the Invoicing Overview and the Invoicing Integration Guide. version: '2.7' contact: {} servers: - url: https://api-m.sandbox.paypal.com description: PayPal Sandbox Environment - url: https://api-m.paypal.com description: PayPal Live Environment security: [] tags: - name: invoices description: >- Use the `/invoices` resource to create, update, and send invoices and invoice reminders. To manage invoices, you can also list invoices, show details for invoices, delete draft invoices, and cancel sent invoices. You can also record payments for invoices to mark them as fully or partially paid, or record refunds for invoices to mark them as fully or partially refunded. You can create QR codes for invoices that can be scanned, viewed, and paid by a mobile phone. - name: search-invoices description: >- Use the `/search-invoices` resource to search for and list invoices that match search criteria. - 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.
Note: To upload a logo to display on an invoice, you can use the Template Settings dashboard to create a template. When you create an invoice, you can use the URI for that logo.
- name: merchant-config description: >- Use the `/merchant-config` resource to create, update and show details of merchant configuration. - name: estimates description: Use the /estimate resource to create, update, and send estimates. - name: batch-tasks description: >- Use the /batch-tasks resource to create, delete and retrieve batch related tasks. - name: stored-discounts description: >- Use the /stored-discounts resource to create and retrieve stored-discounts are specific to merchants - name: Search Enhancement description: >- This section contains the list of api, used to power invoicing search based on Index Organised Table(s). - name: Invoicing Multi Tenancy description: This section contains api to get the tenant config details. - name: Invoice Notification description: >- Use the /email-status-feedback resource to post the status update against invoicing emails. - name: Customer Feedbacks description: >- Use the /customer-feedbacks resource to create and retrieve feedbacks specific to merchants. - name: Insights description: >- Use the /insights resource to retrieve aggregated metrics specific to merchants. - name: invoicing-product-features description: >- This section contains the list of invoicing-product-features related api's. - name: conditional-rules description: This section contains api's related to conditional rules. - name: invoice-payment-attempt description: This section contains api's related to invoice payment attempt. - name: connections description: >- Use the `accounting-sync/merchants/connections` resource to get active connections list. - name: invoice-connection-details description: >- Use the `accounting-sync/invoices/{id}/connections` resource to get active connections list. - name: Invoicing themes description: >- Use the /themes resource to create, update and get details of themes related to merchants. - name: Bulk Sync Invoices - Accounting Sync description: >- Use the /accounting-invoices-batch resource to bulk sync invoices with accounting software. - name: account closure description: >- Use the /cancel-user-records resource to cancel open records for a user and /get-user-record-count to get count of open records. - name: Accounting sync description: This section contains invoicing APIs related to accounting sync. externalDocs: url: https://developer.paypal.com/docs/api/invoicing/v2/ paths: /v2/invoicing/templates: get: tags: - templates summary: 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.
The user can select which values to show in the business information section of their template. operationId: templates.list parameters: - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/page_size' 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' '500': description: An internal server error has occurred. content: application/json: schema: $ref: '#/components/schemas/error_500' multipart/mixed: schema: $ref: '#/components/schemas/error_500' default: $ref: '#/components/responses/default' security: - Oauth2: - https://uri.paypal.com/services/invoicing/invoices/read components: parameters: fields: name: fields in: query description: >- The fields to return in the response. Value is `all` or `none`. To return only the template name, ID, and default attributes, specify `none`. schema: type: string minLength: 0 maxLength: 2147483647 pattern: ^(all|none)$ default: all page: name: page in: query description: >- The page number to be retrieved, for the list of templates. So, a combination of `page=1` and `page_size=20` returns the first 20 templates. A combination of `page=2` and `page_size=20` returns the next 20 templates. schema: type: integer minimum: 1 maximum: 1000 default: 1 page_size: name: page_size in: query description: The maximum number of templates to return in the response. schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: '400': properties: details: type: array items: anyOf: - title: INVALID_INTEGER_MAX_VALUE properties: issue: type: string enum: - INVALID_INTEGER_MAX_VALUE description: type: string enum: - Value exceeds max value. - title: INVALID_INTEGER_MIN_VALUE properties: issue: type: string enum: - INVALID_INTEGER_MIN_VALUE description: type: string enum: - Value less than minimum value. templates: type: object title: Templates minItems: 1 description: >- An array of merchant-created templates with associated details that include the emails, addresses, and phone numbers from the user's PayPal profile. properties: addresses: $ref: '#/components/schemas/address_portable_list' emails: $ref: '#/components/schemas/email_address' description: An array of emails in the user's PayPal profile. readOnly: true phones: $ref: '#/components/schemas/templates_definitions-phone_detail_list' templates: $ref: '#/components/schemas/template_list' links: $ref: '#/components/schemas/link_description_list' error_400: type: object title: Bad Request Error description: Request is not well-formed, syntactically incorrect, or violates schema. properties: name: type: string enum: - INVALID_REQUEST message: type: string enum: - >- Request is not well-formed, syntactically incorrect, or violates schema. 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_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_500: type: object title: Internal Server Error description: >- This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server. properties: name: type: string enum: - INTERNAL_SERVER_ERROR message: type: string enum: - An internal server error occurred. 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' example: name: INTERNAL_SERVER_ERROR message: An internal server error occurred. debug_id: 90957fca61718 links: - href: >- https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR rel: information_link address_portable_list: type: array description: An array of addresses in the user's PayPal profile. items: $ref: '#/components/schemas/address_portable' readOnly: true minItems: 0 maxItems: 2147483647 email_address: type: string description: >- The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
format: ppaas_common_email_address_v2 minLength: 3 maxLength: 254 pattern: >- ^(?:[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[A-Za-z0-9-]*[A-Za-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$ templates_definitions-phone_detail_list: type: array description: An array of phone numbers in the user's PayPal profile. items: $ref: '#/components/schemas/phone_detail' minItems: 0 maxItems: 2147483647 template_list: type: array description: >- An array of details for each template. If `fields` is `none`, returns only the template name, ID, and default status. items: $ref: '#/components/schemas/template' minItems: 0 maxItems: 2147483647 link_description_list: type: array description: >- An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). readOnly: true items: $ref: '#/components/schemas/link_description' minItems: 0 maxItems: 2147483647 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: $ref: '#/components/schemas/error_location' 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 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: 6 pattern: ^[A-Z]*$ enum: - GET - POST - PUT - DELETE - PATCH error_default: description: The default error response. oneOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/error_401' - $ref: '#/components/schemas/error_403' - $ref: '#/components/schemas/error_404' - $ref: '#/components/schemas/error_409' - $ref: '#/components/schemas/error_415' - $ref: '#/components/schemas/error_422' - $ref: '#/components/schemas/error_429' - $ref: '#/components/schemas/error_500' - $ref: '#/components/schemas/error_503' address_portable: type: object title: Portable Postal Address (Medium-Grained) description: >- The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute). properties: address_line_1: type: string description: >- The first line of the address. For example, number or street. For example, `173 Drury Lane`. Required for data entry and compliance and risk checks. Must contain the full address. maxLength: 300 address_line_2: type: string description: >- The second line of the address. For example, suite or apartment number. maxLength: 300 address_line_3: type: string description: >- The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address. maxLength: 100 admin_area_4: type: string description: >- The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is: maxLength: 100 admin_area_3: type: string description: >- A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is: maxLength: 100 admin_area_2: type: string description: A city, town, or village. Smaller than `admin_area_level_1`. maxLength: 120 admin_area_1: type: string description: >- The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, `CA` and not `California`. Value, by country, is: maxLength: 300 postal_code: type: string description: >- The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code). maxLength: 60 country_code: $ref: '#/components/schemas/country_code' address_details: $ref: '#/components/schemas/address_details' required: - country_code 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' template: type: object title: Template description: The template with invoice details to load with all captured fields. properties: id: type: string description: The ID of the template. readOnly: true maxLength: 30 minLength: 0 pattern: ^[\S\s]*$ name: type: string description: >- The template name.
Note: The template name must be unique.
maxLength: 500 minLength: 1 pattern: ^[\S\s]*$ default_template: type: boolean description: >- Indicates whether this template is the default template. A invoicer can have one default template. template_info: $ref: '#/components/schemas/template_info' description: >- The template details. Includes invoicer business information, invoice recipients, items, and configuration. settings: $ref: '#/components/schemas/template_settings' description: >- The template settings. Describes which fields to show or hide when you create an invoice. unit_of_measure: $ref: '#/components/schemas/unit_of_measure' description: >- The unit of measure for the template. Value is quantity, hours, or amount. standard_template: type: boolean description: >- Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates. readOnly: true links: $ref: '#/components/schemas/link_description_list' link_description: type: object title: Link Description description: >- The request-related [HATEOAS link](/api/rest/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 error_location: type: string description: >- The location of the field that caused the error. Value is `body`, `path`, or `query`. enum: - body - path - query default: body error_401: type: object title: Unauthorized Error description: >- Authentication failed due to missing Authorization header, or invalid authentication credentials. properties: name: type: string enum: - AUTHENTICATION_FAILURE message: type: string enum: - >- Authentication failed due to missing authorization header, or invalid authentication credentials. 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_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' error_415: type: object title: Unsupported Media Type Error description: The server does not support the request payload's media type. properties: name: type: string enum: - UNSUPPORTED_MEDIA_TYPE message: type: string enum: - The server does not support the request payload's media type. 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' error_429: type: object title: Too many requests description: Too many requests. Blocked due to rate limiting. properties: name: type: string enum: - RATE_LIMIT_REACHED message: type: string enum: - Too many requests. Blocked due to rate limiting. debug_id: type: string description: The PayPal internal ID. Used for correlation purposes. error_503: type: object title: Service Unavailable Error description: >- The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime. properties: name: type: string enum: - SERVICE_UNAVAILABLE message: type: string enum: - Service Unavailable. 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' example: name: SERVICE_UNAVAILABLE message: Service Unavailable. debug_id: 90957fca61718 information_link: >- https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE country_code: type: string description: >- The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.
Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
format: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ address_details: type: object title: Address Details description: >- The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example, `address_portable.address_line_1` is usually a combination of `address_details.street_number`, `street_name`, and `street_type`. properties: street_number: type: string description: The street number. maxLength: 100 street_name: type: string description: The street name. Just `Drury` in `Drury Lane`. maxLength: 100 street_type: type: string description: >- The street type. For example, avenue, boulevard, road, or expressway. maxLength: 100 delivery_service: type: string description: >- The delivery service. Post office box, bag number, or post office name. maxLength: 100 building_name: type: string description: >- A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House. maxLength: 100 sub_building: type: string description: >- The first-order entity below a named building or location that represents the sub-premises. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment. maxLength: 100 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 consists of a national destination code (NDC) and subscriber number (SN). minLength: 1 maxLength: 14 pattern: ^[0-9]{1,14}?$ extension_number: type: string description: The extension number. minLength: 1 maxLength: 15 pattern: ^[0-9]{1,15}?$ required: - country_code - national_number phone_type: type: string title: Phone Type description: The phone type. enum: - FAX - HOME - MOBILE - OTHER - PAGER template_info: type: object title: Template Information description: >- The template details. Includes invoicer business information, invoice recipients, items, and configuration. properties: detail: $ref: '#/components/schemas/template_detail' description: >- The template-related details. Includes notes, terms and conditions, memo, and attachments. invoicer: $ref: '#/components/schemas/invoicer_info' description: >- The invoicer information. Includes business name, email, address, phone, fax, tax ID, additional notes, and logo URL. primary_recipients: $ref: '#/components/schemas/definitions-recipient_info_list' additional_recipients: $ref: '#/components/schemas/email_address_list' items: $ref: '#/components/schemas/definitions-item_list' configuration: $ref: '#/components/schemas/template_configuration' description: >- The template configuration details. Includes tax information, tip, and partial payment. amount: $ref: '#/components/schemas/amount_summary_detail' description: >- The invoice amount summary of the item total, discount, tax total, and shipping. due_amount: $ref: '#/components/schemas/money' description: The amount due for the invoice. readOnly: true template_settings: type: object title: Template Settings description: >- The template settings. Sets a template as the default template or edit template. properties: template_item_settings: $ref: '#/components/schemas/template_item_setting_list' template_subtotal_settings: $ref: '#/components/schemas/template_subtotal_setting_list' unit_of_measure: type: string description: The unit of measure for the invoiced item. minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ x-enumDescriptions: - value: QUANTITY description: >- The unit of measure is quantity. This invoice template is typically used for physical goods. - value: HOURS description: >- The unit of measure is hours. This invoice template is typically used for services. - value: AMOUNT description: >- The unit of measure is amount. This invoice template is typically used when only amount is required. enum: - QUANTITY - HOURS - AMOUNT template_detail: type: object title: Template Detail description: >- The template-related details. Includes notes, terms and conditions, memo, and attachments. allOf: - $ref: '#/components/schemas/detail' - properties: payment_term: $ref: '#/components/schemas/payment_term' description: >- The payment due date for the invoice. Value is either but not both term_type or due_date. metadata: $ref: '#/components/schemas/template_metadata' description: >- The audit metadata. Captures all template actions on create and update. invoicer_info: type: object title: Invoicer Information description: The invoicer business information that appears on the invoice. allOf: - $ref: '#/components/schemas/contact_name_address' - properties: email_address: $ref: '#/components/schemas/restrictive_email_address' description: >- The invoicer email address, which must be listed in the user's PayPal profile. If you omit this value, notifications are sent from and to the primary email address but do not appear on the invoice. phones: $ref: '#/components/schemas/phone_detail_list' website: type: string format: uri description: The invoicer's website. maxLength: 2048 tax_id: type: string description: The invoicer's tax ID. maxLength: 100 additional_notes: type: string description: Any additional information. Includes business hours. maxLength: 400 logo_url: type: string format: uri description: >- The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high. maxLength: 2000 definitions-recipient_info_list: type: array items: $ref: '#/components/schemas/recipient_info' minItems: 0 maxItems: 100 description: >- The billing and shipping information. Includes name, email, address, phone, and language. email_address_list: type: array minItems: 0 maxItems: 100 description: >- An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.
Note: Valid values are email addresses in the `additional_recipients` value associated with the invoice.
items: $ref: '#/components/schemas/email_address' definitions-item_list: type: array description: An array of invoice line-item information. minItems: 0 maxItems: 100 items: $ref: '#/components/schemas/item' template_configuration: type: object title: Template Configuration description: >- The template configuration details. Includes tax information, tip, and partial payment. properties: tax_calculated_after_discount: type: boolean description: >- Indicates whether the tax is calculated before or after a discount. If `false`, the tax is calculated before a discount. If `true`, the tax is calculated after a discount. default: true tax_inclusive: type: boolean description: Indicates whether the unit price includes tax. default: false allow_tip: type: boolean description: >- Indicates whether the invoice enables the customer to enter a tip amount during payment. If `true`, the invoice shows a tip amount field so that the customer can enter a tip amount. If `false`, the invoice does not show a tip amount field.
Note: This feature is not available for users in `Hong Kong`, `Taiwan`, `India`, or `Japan`.
default: false partial_payment: $ref: '#/components/schemas/partial_payment' description: >- The partial payment details. Includes the minimum amount that the invoicer wants the payer to pay. has_conditional_rule: type: boolean description: >- Indicates whether conditional pricing rules are applied to the invoice. If `true`, pricing rules (such as discounts or surcharges based on specific conditions) are applied. If `false`, no conditional pricing rules are applied. default: false amount_summary_detail: type: object title: Invoice Amount Summary description: >- The invoice amount summary of item total, discount, tax total, and shipping. properties: currency_code: $ref: '#/components/schemas/currency_code' value: type: string description: >- The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/). minLength: 0 maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ breakdown: $ref: '#/components/schemas/amount_with_breakdown' description: >- The breakdown of the amount. Breakdown provides details such as total item amount, total tax amount, custom amount, shipping and discounts, if any. money: type: object title: Money description: >- The currency and amount for a financial transaction, such as a balance or payment due. properties: currency_code: $ref: '#/components/schemas/currency_code' value: type: string description: >- The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). maxLength: 32 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ required: - currency_code - value template_item_setting_list: type: array minItems: 0 maxItems: 2147483647 description: The template item headers display preference. items: $ref: '#/components/schemas/template_item_setting' template_subtotal_setting_list: type: array minItems: 0 maxItems: 2147483647 description: The template subtotal headers display preference. items: $ref: '#/components/schemas/template_subtotal_setting' detail: title: Invoice_Detail description: >- The details of the invoice like notes, terms and conditions, memo, attachments. required: - currency_code properties: reference: type: string description: The reference data. Includes a Purchase Order (PO) number. pattern: ^[\S\s]*$ minLength: 0 maxLength: 120 currency_code: $ref: '#/components/schemas/currency_code' description: >- The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency. note: type: string description: >- A note to the invoice recipient. Also appears on the invoice notification email. pattern: ^[\S\s]*$ minLength: 0 maxLength: 4000 terms_and_conditions: type: string description: >- The general terms of the invoice. Can include return or cancellation policy and other terms and conditions. pattern: ^[\S\s]*$ minLength: 0 maxLength: 4000 memo: type: string description: A private bookkeeping memo for the user. pattern: ^[\S\s]*$ minLength: 0 maxLength: 500 attachments: $ref: '#/components/schemas/file_reference_list' 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: $ref: '#/components/schemas/payment_term_type' description: >- The payment term. Payment can be due upon receipt, a specified date, or in a set number of days. template_metadata: type: object title: Template Metadata description: The audit metadata. Captures all template actions on create and update. properties: create_time: $ref: '#/components/schemas/date_time' description: >- The date and time when the resource was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true created_by: type: string description: The email address of the account that created the resource. readOnly: true minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ last_update_time: $ref: '#/components/schemas/date_time' description: >- The date and time when the resource was last edited, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true last_updated_by: type: string description: The email address of the account that last edited the resource. readOnly: true minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ contact_name_address: type: object title: Contact Information description: The contact information of the user. Includes name and address. allOf: - $ref: '#/components/schemas/business_name' - properties: name: $ref: '#/components/schemas/name' description: The first and Last name of the recipient. address: $ref: '#/components/schemas/address_portable' description: The address of the recipient. restrictive_email_address: type: string description: >- The internationalized email address with more restrictive rules. This version restricts the local-part to a dot-atom as defined in https://www.ietf.org/rfc/rfc5322.txt. It does not allow for a quoted-string or an obs-local-part.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.
minLength: 3 maxLength: 254 pattern: >- ^(?!\.)(?:[A-Za-z0-9!#$&'*\/=?^`{|}~_%+-]|\.(?!\.)){1,64}(?- An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice. recipient_info: type: object title: Recipient Information description: >- The billing and shipping information. Includes name, email, address, phone, and language. properties: billing_info: $ref: '#/components/schemas/billing_info' description: >- The billing information for the invoice recipient. Includes name, address, email, phone, and language. shipping_info: $ref: '#/components/schemas/contact_name_address' description: >- The recipient's shipping information. Includes the user's contact information, which includes name and address. 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 pattern: ^[\S\s]*$ minLength: 0 maxLength: 22 name: type: string description: The item name for the invoice line item. pattern: ^[\S\s]*$ minLength: 0 maxLength: 200 description: type: string description: The item description for the invoice line item. pattern: ^[\S\s]*$ minLength: 0 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. pattern: \d+(.\d{1,5})?$ 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: $ref: '#/components/schemas/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.
Note: If your specify different `unit_of_measure` values for the same invoice, the invoice uses the first value.
required: - name - quantity - unit_amount partial_payment: type: object title: Partial Payment description: >- The partial payment details. Includes the minimum amount that the invoicer expects from the payer. properties: allow_partial_payment: type: boolean description: >- Indicates whether the invoice allows a partial payment. If `false`, the invoice must be paid in full. If `true`, the invoice allows partial payments.
Note: This feature is not available for users in `India`, `Brazil`, or `Israel`.
default: false minimum_amount_due: $ref: '#/components/schemas/money' description: >- The minimum amount allowed for a partial payment. Valid only when `allow_partial_payment` is `true`. currency_code: description: >- The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string minLength: 3 maxLength: 3 x-security-classification: data_class: class4 data_category: INTRINSIC amount_with_breakdown: type: object title: Amount with Breakdown description: >- The breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any. properties: item_total: $ref: '#/components/schemas/money' description: >- The subtotal for all items. Must equal the sum of (`items[].unit_amount` * `items[].quantity`) for all items. discount: $ref: '#/components/schemas/aggregated_discount' description: >- The discount can be at the item or invoice level, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent. tax_total: $ref: '#/components/schemas/money' description: The aggregated amount of the item and shipping taxes. shipping: $ref: '#/components/schemas/shipping_cost' description: The shipping fee for all items. Includes tax on shipping. custom: $ref: '#/components/schemas/custom_amount' description: >- The custom amount to apply to an invoice. If you include a label, you must include the custom amount. template_item_setting: type: object title: Template Item Setting description: >- The template item setting. Sets a template as the default template or edit template. properties: field_name: $ref: '#/components/schemas/template_item_field' description: >- The field name in `template_data` for which to map corresponding display preferences. display_preference: $ref: '#/components/schemas/template_display_preference' description: The display preference. template_subtotal_setting: type: object title: Template Subtotal Setting description: >- The template subtotal setting. Includes the field name and display preference. properties: field_name: $ref: '#/components/schemas/template_subtotal_field' description: >- The field name in `template_data` for which to map corresponding display preferences. display_preference: $ref: '#/components/schemas/template_display_preference' description: The display preference. file_reference_list: type: array description: An array of PayPal IDs for the files that are attached to an invoice. minItems: 0 maxItems: 2147483647 items: $ref: '#/components/schemas/file_reference' 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. minLength: 0 maxLength: 255 pattern: ^[\S\s]*$ x-enumDescriptions: - value: DUE_ON_RECEIPT description: The payment for the invoice is due upon receipt of the invoice. - value: DUE_ON_DATE_SPECIFIED description: >- The payment for the invoice is due on the date specified in the invoice. - value: NET_10 description: The payment for the invoice is due in 10 days. - value: NET_15 description: The payment for the invoice is due in 15 days. - value: NET_30 description: The payment for the invoice is due in 30 days. - value: NET_45 description: The payment for the invoice is due in 45 days. - value: NET_60 description: The payment for the invoice is due in 60 days. - value: NET_90 description: The payment for the invoice is due in 90 days. - value: NO_DUE_DATE description: The invoice has no payment due date. enum: - DUE_ON_RECEIPT - DUE_ON_DATE_SPECIFIED - NET_10 - NET_15 - NET_30 - NET_45 - NET_60 - NET_90 - NO_DUE_DATE date_time: type: string description: >- The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
format: ppaas_date_time_v3 minLength: 20 maxLength: 64 pattern: >- ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$ business_name: type: object title: Business Name description: The business name of the party. properties: business_name: type: string description: Required. The business name of the party. maxLength: 300 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 billing_info: type: object title: Billing Information description: >- The billing information of the invoice recipient. Includes name, address, email, phone, and language. allOf: - $ref: '#/components/schemas/contact_name_address' - properties: email_address: $ref: '#/components/schemas/restrictive_email_address' description: >- The invoice recipient email address. If you omit this value, the invoice is payable and a notification email is not sent. phones: $ref: '#/components/schemas/definitions-phone_detail_list' additional_info: type: string description: Any additional information about the recipient. maxLength: 40 language: $ref: '#/components/schemas/language' description: >- The language in which to show the invoice recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account. tax: type: object title: Tax description: >- The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total. properties: name: type: string description: The name of the tax applied on the invoice items. maxLength: 100 minLength: 0 pattern: ^[\s\S]*$ percent: $ref: '#/components/schemas/percentage' description: >- The tax rate. Value is from `0` to `100`. Supports up to five decimal places. amount: $ref: '#/components/schemas/money' description: >- The calculated tax amount. The tax amount is added to the item total. readOnly: true tax_note: type: string description: The tax note used to track the tax related data. maxLength: 40 minLength: 0 pattern: ^[\s\S]*$ required: - name - percent 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])$ discount: type: object title: Discount description: >- The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total. properties: percent: $ref: '#/components/schemas/percentage' description: >- The discount as a percentage value. Value is from `0` to `100`. Supports up to five decimal places. amount: $ref: '#/components/schemas/money' description: >- The invoice level discount amount. Value is from `0` to `1000000`. Supports up to two decimal places. 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. shipping_cost: type: object title: Shipping Cost description: The shipping fee for all items. Includes tax on shipping. properties: amount: $ref: '#/components/schemas/money' description: >- The shipping amount. Value is from `0` to `1000000`. Supports up to two decimal places. tax: $ref: '#/components/schemas/tax' description: The tax associated with the shipping. custom_amount: type: object title: Custom Amount description: >- The custom amount to apply to an invoice. If you include a label, you must include a custom amount. required: - label properties: label: type: string description: The label to the custom amount of the invoice. pattern: ^[\S\s]*$ minLength: 0 maxLength: 50 amount: $ref: '#/components/schemas/money' description: >- The custom amount value. Value is from `-1000000` to `1000000`. Supports up to two decimal places. template_item_field: type: string title: Template Item Field description: The field names for the invoice line items in the template. minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ x-enumDescriptions: - value: ITEMS_QUANTITY description: >- The quantity of the item in the template that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places. - value: ITEMS_DESCRIPTION description: The description of the item in the invoice template. - value: ITEMS_DATE description: >- The date in invoice template 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*. - value: ITEMS_DISCOUNT description: >- The item discount in the invoice template. Discount as a percent or amount at invoice level. Invoice discount amount is subtracted from the item total. - value: ITEMS_TAX description: >- The tax associated with the item in the invoice template. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places. enum: - ITEMS_QUANTITY - ITEMS_DESCRIPTION - ITEMS_DATE - ITEMS_DISCOUNT - ITEMS_TAX 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 template_subtotal_field: type: string title: Template Subtotal Field description: >- The field names in the template for discount, shipping, and custom amounts. minLength: 0 maxLength: 2147483647 pattern: ^[\S\s]*$ x-enumDescriptions: - value: DISCOUNT description: >- The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total. - value: SHIPPING description: >- The shipping fee for all items in the invoice template. Also includes the tax on shipping. - value: CUSTOM description: >- The custom amount to apply to an invoice in the template. If you include a label, you must include the custom amount. enum: - DISCOUNT - SHIPPING - CUSTOM 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]+$ definitions-phone_detail_list: type: array items: $ref: '#/components/schemas/phone_detail' description: >- The invoice recipient's phone numbers. Extension number is not supported. 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](/api/rest/reference/country-codes/) or [M49 region code](https://unstats.un.org/unsd/methodology/m49/). format: ppaas_common_language_v3 maxLength: 10 minLength: 2 pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$ percentage: type: string description: >- The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`. format: ppaas_common_percentage_v2 pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$ responses: default: description: The default response. content: application/json: schema: $ref: '#/components/schemas/error_default' securitySchemes: Oauth2: type: oauth2 description: Oauth 2.0 authentication flows: clientCredentials: tokenUrl: /v1/oauth2/token scopes: https://uri.paypal.com/services/invoicing/invoices/read: For Reading the invoice details. https://uri.paypal.com/services/invoicing/invoices/readwrite: For managing (Create, Update, Delete) invoice. https://uri.paypal.com/services/invoicing/internal: Manage invoice resource internal clients. ````