> ## 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. # Search for invoices > Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria. ## OpenAPI ````yaml /api-reference/invoicing_v2.json post /v2/invoicing/search-invoices 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/search-invoices: post: tags: - search-invoices summary: Search for invoices description: >- Searches for and lists invoices that match search criteria. If you pass multiple criteria, the response lists invoices that match all criteria. operationId: invoices.search-invoices parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/page_size' - $ref: '#/components/parameters/total_required' requestBody: content: application/json: schema: $ref: '#/components/schemas/search_data' description: >- The invoice search can be used to retrieve the invoices based on the search parameters. responses: '200': description: >- A successful request returns the HTTP `200 OK` status code and a JSON response body that lists the invoices that match the search criteria. content: application/json: schema: $ref: '#/components/schemas/invoices' multipart/mixed: schema: $ref: '#/components/schemas/invoices' '400': description: Invalid request. content: application/json: schema: allOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/invoices.search-invoices-400' multipart/mixed: schema: allOf: - $ref: '#/components/schemas/error_400' - $ref: '#/components/schemas/invoices.search-invoices-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: 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 total_required: name: total_required in: query description: >- Indicates whether the to show total_pages and total_items in the response. schema: type: boolean default: false schemas: search_data: type: object title: Search Data description: The invoice search parameters. properties: recipient_email: type: string pattern: ^[\S\s]*$ minLength: 0 maxLength: 254 description: Filters the search by the email address. recipient_first_name: type: string description: Filters the search by the recipient first name. pattern: ^[\S\s]*$ minLength: 0 maxLength: 140 recipient_last_name: type: string description: Filters the search by the recipient last name. pattern: ^[\S\s]*$ minLength: 0 maxLength: 140 recipient_business_name: type: string description: Filters the search by the recipient business name. pattern: ^[\S\s]*$ minLength: 0 maxLength: 300 invoice_number: type: string pattern: ^[\S\s]*$ minLength: 0 maxLength: 25 description: Filters the search by the invoice number. status: $ref: '#/components/schemas/invoice_status_list' 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. memo: type: string description: A private bookkeeping memo for the user. pattern: ^[\S\s]*$ minLength: 0 maxLength: 500 total_amount_range: $ref: '#/components/schemas/amount_range' description: Filters the search by the total amount. invoice_date_range: $ref: '#/components/schemas/date_range' description: >- Filters the search by a date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). due_date_range: $ref: '#/components/schemas/date_range' description: >- Filters the search by a due date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). payment_date_range: $ref: '#/components/schemas/date_time_range' creation_date_range: $ref: '#/components/schemas/date_time_range' description: >- Filters the search by a creation date range for the invoice, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). archived: type: boolean description: >- Indicates whether to list merchant-archived invoices in the response. Value is: fields: $ref: '#/components/schemas/fields_list' invoices: type: object title: Invoices minItems: 1 description: >- An array of merchant invoices. Includes the total invoices count and [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links) for navigation. properties: total_pages: type: integer description: >- The total number of pages that are available for the search criteria.
Note: Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next
readOnly: true minimum: 0 maximum: 2147483647 total_items: type: integer description: >- The total number of invoices that match the search criteria.
Note: Clients MUST NOT assume that the value of total_items is constant. The value MAY change from one request to the next.
readOnly: true minimum: 0 maximum: 2147483647 items: $ref: '#/components/schemas/invoice_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' invoices.search-invoices-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. - title: INVALID_STRING_MAX_LENGTH properties: issue: type: string enum: - INVALID_STRING_MAX_LENGTH description: type: string enum: - the value of a field is too long. - title: INVALID_ARRAY_MAX_ITEMS properties: issue: type: string enum: - INVALID_ARRAY_MAX_ITEMS description: type: string enum: - the number of items in an array parameter is too large. - title: INVALID_STRING_LENGTH properties: issue: type: string enum: - INVALID_STRING_LENGTH description: type: string enum: - the value of a 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: - the value of a field is too long. - title: INVALID_PARAMETER_SYNTAX properties: issue: type: string enum: - INVALID_PARAMETER_SYNTAX description: type: string enum: - >- the value of a field does not conform to the expected format. 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 invoice_status_list: type: array description: An array of status values. items: $ref: '#/components/schemas/invoice_status' minItems: 0 maxItems: 5 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_range: type: object title: Amount Range description: The amount range. properties: lower_amount: $ref: '#/components/schemas/money' description: The lower limit of the amount range. upper_amount: $ref: '#/components/schemas/money' description: The upper limit of the amount range. required: - lower_amount - upper_amount date_range: type: object title: Date Range description: >- The date range. Filters invoices by creation date, invoice date, due date, and payment date. properties: start: $ref: '#/components/schemas/date_no_time' description: >- The start date of the range. Filters invoices by creation date, invoice date, due date, and payment date. end: $ref: '#/components/schemas/date_no_time' description: >- The end date of the range. Filters invoices by creation date, invoice date, due date, and payment date. required: - start - end date_time_range: type: object title: Date and Time Range description: >- The date and time range. Filters invoices by creation date, invoice date, due date, and payment date. properties: start: $ref: '#/components/schemas/date_time' description: >- The start date of the range. Filters invoices by creation date, invoice date, due date, and payment date. end: $ref: '#/components/schemas/date_time' description: >- The end date of the range. Filters invoices by creation date, invoice date, due date, and payment date.
Note: The regular expression provides guidance but does not reject all invalid dates.

Minimum length: 20.
Maximum length: 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})$ required: - start - end fields_list: description: >- A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are items, payments, refunds, additional_recipients_info, and attachments. type: array minItems: 0 maxItems: 5 items: $ref: '#/components/schemas/fields' invoice_list: type: array description: The list of invoices that match the search criteria. readOnly: true items: $ref: '#/components/schemas/invoice' minItems: 0 maxItems: 100 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' invoice_status: type: string title: Invoice Status description: The status of the invoice. minLength: 0 maxLength: 255 pattern: ^[\s\S]*$ x-enumDescriptions: - value: DRAFT description: The invoice is in draft state. It is not yet sent to the payer. - value: SENT description: >- The invoice has been sent to the payer. The payment is awaited from the payer. - value: SCHEDULED description: >- The invoice is scheduled on a future date. It is not yet sent to the payer. - value: PAID description: The payer has paid for the invoice. - value: MARKED_AS_PAID description: The invoice is marked as paid by the invoicer. - value: CANCELLED description: The invoice has been cancelled by the invoicer. - value: REFUNDED description: The invoice has been refunded by the invoicer. - value: PARTIALLY_PAID description: The payer has partially paid for the invoice. - value: PARTIALLY_REFUNDED description: The invoice has been partially refunded by the invoicer. - value: MARKED_AS_REFUNDED description: The invoice is marked as refunded by the invoicer. - value: UNPAID description: >- The invoicer is yet to receive the payment from the payer for the invoice. - value: PAYMENT_PENDING description: >- The invoicer is yet to receive the payment for the invoice. It is under pending review. - value: AUTO_CANCELLED description: >- The invoice was automatically cancelled because the payment was not received within the specified timeframe. - value: PAID_EXTERNAL description: >- The invoice has been paid through an external system or method outside of the standard PayPal payment flow. This status is set manually, indicating payment was received through other means. - value: REFUNDED_EXTERNAL description: >- The invoice has been refunded through an external system or method. This status indicates a refund was issued outside of the standard PayPal payment flow. - value: SHARED description: >- The invoice has been shared with the payer, typically via a link or other method. This status is used to track when an invoice has been distributed but not necessarily sent via PayPal. enum: - DRAFT - SENT - SCHEDULED - PAID - MARKED_AS_PAID - CANCELLED - REFUNDED - PARTIALLY_PAID - PARTIALLY_REFUNDED - MARKED_AS_REFUNDED - UNPAID - PAYMENT_PENDING - AUTO_CANCELLED - PAID_EXTERNAL - REFUNDED_EXTERNAL - SHARED 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 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])$ 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})$ fields: type: string description: The name of the field. pattern: ^[\S\s]*$ minLength: 0 maxLength: 2147483647 invoice: type: object title: Invoice description: >- The invoice details which includes all information of the invoice like items, billing information. required: - detail properties: id: type: string description: The ID of the invoice. readOnly: true pattern: ^[\s\S]*$ minLength: 0 maxLength: 30 parent_id: type: string description: >- The parent ID to an invoice that defines the group invoice to which the invoice is related. readOnly: true pattern: ^[\s\S]*$ minLength: 0 maxLength: 30 status: $ref: '#/components/schemas/invoice_status' readOnly: true detail: $ref: '#/components/schemas/invoice_detail' description: >- The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata. invoicer: $ref: '#/components/schemas/invoicer_info' description: >- The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL. primary_recipients: $ref: '#/components/schemas/recipient_info_list' additional_recipients: $ref: '#/components/schemas/email_address_list' items: $ref: '#/components/schemas/item_list' configuration: $ref: '#/components/schemas/configuration' description: >- The invoice configuration details. Includes partial payment, tip, and tax calculated after discount. amount: $ref: '#/components/schemas/amount_summary_detail' description: >- The invoice amount summary of item total, discount, tax total and shipping.. due_amount: $ref: '#/components/schemas/money' description: >- The due amount, which is the balance amount outstanding after payments. readOnly: true gratuity: $ref: '#/components/schemas/money' description: The amount paid by the payer as gratuity to the invoicer. readOnly: true payments: $ref: '#/components/schemas/payments' description: List of payments registered against the invoice.. refunds: $ref: '#/components/schemas/refunds' description: >- List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method. 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 invoice_detail: type: object title: Invoice Detail description: >- The details of the invoice. Includes invoice number, date, payment terms, and audit metadata. allOf: - $ref: '#/components/schemas/detail' - properties: invoice_number: type: string description: >- The invoice number. Default is the number that is auto-incremented number from the last number. maxLength: 25 invoice_date: $ref: '#/components/schemas/date_no_time' description: >- The invoice date as specificed by the sender, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Only UTC is supported in response. For example, *yyyy*-*MM*-*dd*T*z*. payment_term: $ref: '#/components/schemas/invoice_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/metadata' description: >- The audit metadata. Captures all invoicing actions on create, send, update, and cancel. readOnly: true 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 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' item_list: type: array description: An array of invoice line item information. minItems: 0 maxItems: 100 items: $ref: '#/components/schemas/item' configuration: type: object title: Configuration description: >- The invoice configuration details. Includes partial payment, tip, and tax calculated after discount. allOf: - $ref: '#/components/schemas/template_configuration' - properties: template_id: type: string description: >- The template ID. The template determines the layout of the invoice. Includes which fields to show and hide.
Note: This is an optional field. If you wish to customize the invoice layout using a specific template, provide a valid template ID here. You can either use an existing template ID or create a new template via the create template API and then use the newly created template's ID.
default: PayPal system template maxLength: 30 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. payments: type: object title: Payments description: An array of payments registered against the invoice. properties: paid_amount: $ref: '#/components/schemas/money' readOnly: true description: The aggregated payment amounts against this invoice. transactions: $ref: '#/components/schemas/payment_detail_list' refunds: type: object title: Refunds description: >- The invoicing refund details. Includes the refund type, date, amount, and method. properties: refund_amount: $ref: '#/components/schemas/money' readOnly: true description: The aggregated refund amounts. transactions: $ref: '#/components/schemas/refund_detail_list' 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' invoice_payment_term: type: object title: Invoice 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. allOf: - $ref: '#/components/schemas/payment_term' - properties: due_date: $ref: '#/components/schemas/date_no_time' description: >- The date when the invoice payment is due, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*. metadata: type: object title: Metadata description: >- The audit metadata. Captures all invoicing actions on create, send, update, and cancel. allOf: - $ref: '#/components/schemas/template_metadata' - properties: cancel_time: $ref: '#/components/schemas/date_time' description: >- The date and time when the resource was canceled, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true cancelled_by: type: string description: The actor who canceled the resource. readOnly: true first_sent_time: $ref: '#/components/schemas/date_time' description: >- The date and time when the resource was first sent, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true last_sent_time: $ref: '#/components/schemas/date_time' description: >- The date and time when the resource was last sent, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true last_sent_by: type: string description: The email address of the account that last sent the resource. readOnly: true created_by_flow: $ref: '#/components/schemas/invoice_creation_flow' description: The flow variation that created this invoice. readOnly: true recipient_view_url: type: string readOnly: true format: uri description: The URL for the invoice payer view hosted on paypal.com. invoicer_view_url: type: string readOnly: true format: uri description: The URL for the invoice merchant view hosted on paypal.com. 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. 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])+)\])$ 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 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_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. payment_detail_list: type: array description: >- An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type. minItems: 0 maxItems: 100 items: $ref: '#/components/schemas/payment_detail' readOnly: true refund_detail_list: type: array description: >- An array of refund details for the invoice. Includes the refund type, date, amount, and method. minItems: 0 maxItems: 100 items: $ref: '#/components/schemas/refund_detail' readOnly: true 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: 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]*$ invoice_creation_flow: type: string title: Invoice Creation Flow description: >- The frequency at which the invoice is sent: minLength: 0 maxLength: 255 pattern: ^[\s\S]*$ x-enumDescriptions: - value: MULTIPLE_RECIPIENTS_GROUP description: The invoice sent to multiple recipients. - value: BATCH description: The invoice sent as a batch. - value: REGULAR_SINGLE description: The regular invoice sent to single recipient. enum: - MULTIPLE_RECIPIENTS_GROUP - BATCH - REGULAR_SINGLE 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 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' 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 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. 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 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`. 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. payment_detail: type: object title: Payment Detail description: >- The payment details of the invoice. Includes payment type, method, date, discount, and transaction type. properties: type: $ref: '#/components/schemas/payment_type' description: >- The payment type in an invoicing flow which can be PayPal or an external cash or check payment. readOnly: true payment_id: type: string description: >- The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type. pattern: ^[\S\s]*$ minLength: 0 maxLength: 22 payment_date: $ref: '#/components/schemas/date_no_time' description: >- The date when the invoice was paid, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd* *z*. payment_date_time: $ref: '#/components/schemas/date_time' description: >- The date-time when the invoice was paid. For example, *yyyy*-*MM*-*dd* *T* *HH*: *mm*: *ss* *z*. The time zone will be UTC. method: $ref: '#/components/schemas/payment_method' description: >- The payment mode or method through which the invoicer can accept the payment. note: type: string description: A note associated with an external cash or check payment. pattern: ^[\S\s]*$ minLength: 0 maxLength: 2000 amount: $ref: '#/components/schemas/money' description: >- The payment amount to record against the invoice. If you omit this parameter, the total invoice amount is marked as paid. This amount cannot exceed the amount due. 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. required: - method refund_detail: type: object title: Refund Detail description: >- The refund details of the invoice. Includes the refund type, date, amount, and method. properties: type: $ref: '#/components/schemas/payment_type' description: >- The PayPal refund type. Indicates whether the refund was paid through PayPal or externally in the invoicing flow. The record refund method supports the `EXTERNAL` refund type. The `PAYPAL` refund type is supported for backward compatibility. readOnly: true refund_id: type: string description: >- The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type. pattern: ^[\S\s]*$ minLength: 0 maxLength: 22 readOnly: true refund_date: $ref: '#/components/schemas/date_no_time' description: >- The date when the invoice was refunded, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, `2014-02-27`. amount: $ref: '#/components/schemas/money' description: >- The amount to record as refunded. If you omit the amount, the total invoice paid amount is recorded as refunded. method: $ref: '#/components/schemas/payment_method' description: >- The payment mode or method through which the invoicer can accept the payments. required: - method 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]+$ 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 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 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]+))$ payment_type: type: string title: Payment Type description: >- The payment type. Can be PayPal or an external payment. Includes cash or a check. minLength: 0 maxLength: 255 pattern: ^[\S\s]*$ x-enumDescriptions: - value: PAYPAL description: The payment type is PayPal. - value: EXTERNAL description: The payment type is an external cash or a check payment. enum: - PAYPAL - EXTERNAL payment_method: type: string title: Payment Method description: >- The payment mode or method through which the invoicer can accept the payments. minLength: 0 maxLength: 255 pattern: ^[\S\s]*$ x-enumDescriptions: - value: BANK_TRANSFER description: Payments can be received through bank transfers. - value: CASH description: Payments can be received as cash. - value: CHECK description: Payments can be received as check. - value: CREDIT_CARD description: Payments can be received through credit card payments. - value: DEBIT_CARD description: Payments can be received through debit card payments. - value: PAYPAL description: Payments can be received through paypal payments. - value: WIRE_TRANSFER description: Payments can be received through wire transfer. - value: OTHER description: Payments can be received through other modes. enum: - BANK_TRANSFER - CASH - CHECK - CREDIT_CARD - DEBIT_CARD - PAYPAL - WIRE_TRANSFER - OTHER 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. ````