openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Search-Invoices API
  description: You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see <a href="/docs/subscriptions/">Subscriptions Overview</a>.
  version: '1.6'
  contact: {}
servers:
- url: https://api-m.sandbox.paypal.com
  description: PayPal Sandbox Environment
- url: https://api-m.paypal.com
  description: PayPal Live Environment
tags:
- name: Search-Invoices
  description: Use the `/search-invoices` resource to search for and list invoices that match search criteria.
paths:
  /v2/invoicing/search-invoices:
    post:
      summary: Paypal 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
      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'
        default:
          $ref: '#/components/responses/default'
      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'
            examples:
              '0':
                $ref: '#/components/examples/search_data'
        description: The invoice search can be used to retrieve the invoices based on the search parameters.
      security:
      - Oauth2:
        - https://uri.paypal.com/services/invoicing/invoices/read
      tags:
      - Search-Invoices
components:
  schemas:
    file_reference:
      type: object
      title: File Reference
      description: The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or other custom store.
      properties:
        id:
          type: string
          description: The ID of the referenced file.
          minLength: 1
          maxLength: 255
        reference_url:
          type: string
          description: The reference URL for the file.
          format: uri
          minLength: 1
          maxLength: 2000
        content_type:
          type: string
          description: The [Internet Assigned Numbers Authority (IANA) media type of the file](https://www.iana.org/assignments/media-types/media-types.xhtml).
        create_time:
          $ref: '#/components/schemas/date_time'
          description: The date and time when the file was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
        size:
          type: string
          description: The size of the file, in bytes.
          pattern: ^[0-9]+$
    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'
    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:
          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.
          maxItems: 100
          items:
            $ref: '#/components/schemas/payment_detail'
          readOnly: true
    language:
      type: string
      description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/).
      format: ppaas_common_language_v3
      maxLength: 10
      minLength: 2
      pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$
    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'
    invoice_creation_flow:
      type: string
      title: Invoice Creation Flow
      description: The frequency at which the invoice is sent:<ul><li>Multiple recipient. Sent to multiple recipients.</li><li>Batch. Sent in a batch.</li><li>Regular single. Sent one time to a single recipient.</li></ul>
      enum:
      - MULTIPLE_RECIPIENTS_GROUP
      - BATCH
      - REGULAR_SINGLE
    payment_term:
      type: object
      title: Payment Term
      description: The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days.
      properties:
        term_type:
          description: The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
          $ref: '#/components/schemas/payment_term_type'
    phone_type:
      type: string
      title: Phone Type
      description: The phone type.
      enum:
      - FAX
      - HOME
      - MOBILE
      - OTHER
      - PAGER
    link_description:
      type: object
      title: Link Description
      description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
      required:
      - href
      - rel
      properties:
        href:
          type: string
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
        rel:
          type: string
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
        method:
          type: string
          description: The HTTP method required to make the related call.
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - HEAD
          - CONNECT
          - OPTIONS
          - PATCH
    item:
      type: object
      title: Invoice Item
      description: An array of invoice line item information. The maximum items for an invoice is `100`.
      properties:
        id:
          type: string
          description: The ID of the invoice line item.
          readOnly: true
          maxLength: 22
        name:
          type: string
          description: The item name for the invoice line item.
          maxLength: 200
        description:
          type: string
          description: The item description for the invoice line item.
          maxLength: 1000
        quantity:
          type: string
          maxLength: 14
          minLength: 0
          description: The quantity of the item that the invoicer provides to the payer. Value is from `-1000000` to `1000000`. Supports up to five decimal places.
        unit_amount:
          $ref: '#/components/schemas/money'
          description: The unit price of the item. This does not include tax and discount. Value is from `-1000000` to `1000000`. Supports up to two decimal places.
        tax:
          $ref: '#/components/schemas/tax'
          description: The tax associated with the item. The tax amount is added to the item total. Value is from `0` to `100`. Supports up to five decimal places.
        item_date:
          $ref: '#/components/schemas/date_no_time'
          description: The date when the item or service was provided, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). For example, *yyyy*-*MM*-*dd*T*z*.
        discount:
          $ref: '#/components/schemas/discount'
          description: Discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
        unit_of_measure:
          description: The unit of measure for the invoiced item. For `AMOUNT` the `unit_amount` and `quantity` are not shown on the invoice.<blockquote><strong>Note:</strong> If your specify different `unit_of_measure` values for the same invoice, the invoice uses the first value.</blockquote>
          $ref: '#/components/schemas/unit_of_measure'
      required:
      - name
      - quantity
      - unit_amount
    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])$
    payment_term_type:
      type: string
      title: Payment Term Type
      description: The payment term. Payment can be due upon receipt, a specified date, or in a set number of days.
      enum:
      - DUE_ON_RECEIPT
      - DUE_ON_DATE_SPECIFIED
      - NET_10
      - NET_15
      - NET_30
      - NET_45
      - NET_60
      - NET_90
      - NO_DUE_DATE
    aggregated_discount:
      type: object
      title: Aggregated Discount
      description: The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent.
      properties:
        invoice_discount:
          $ref: '#/components/schemas/discount'
          description: The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total.
        item_discount:
          $ref: '#/components/schemas/money'
          description: The discount as a percent or amount at item level. The item discount amount is subtracted from each item amount.
    error_403:
      type: object
      title: Not Authorized Error
      description: 'The client is not authorized to access this resource, although it may have valid credentials. '
      properties:
        name:
          type: string
          enum:
          - NOT_AUTHORIZED
        message:
          type: string
          enum:
          - Authorization failed due to insufficient permissions.
        details:
          type: array
          items:
            $ref: '#/components/schemas/error_details'
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            $ref: '#/components/schemas/error_link_description'
    invoice_status:
      type: string
      title: Invoice Status
      description: The status of the invoice.
      enum:
      - DRAFT
      - SENT
      - SCHEDULED
      - PAID
      - MARKED_AS_PAID
      - CANCELLED
      - REFUNDED
      - PARTIALLY_PAID
      - PARTIALLY_REFUNDED
      - MARKED_AS_REFUNDED
      - UNPAID
      - PAYMENT_PENDING
    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_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_details:
      title: Error Details
      type: object
      description: The error details. Required for client-side `4XX` errors.
      properties:
        field:
          type: string
          description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
        value:
          type: string
          description: The value of the field that caused the error.
        location:
          type: string
          description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
          default: body
        issue:
          type: string
          description: The unique, fine-grained application-level error code.
        description:
          type: string
          description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
      required:
      - issue
    name:
      type: object
      title: Name
      description: The name of the party.
      properties:
        prefix:
          type: string
          description: The prefix, or title, to the party's name.
          maxLength: 140
        given_name:
          type: string
          description: When the party is a person, the party's given, or first, name.
          maxLength: 140
        surname:
          type: string
          description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
          maxLength: 140
        middle_name:
          type: string
          description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
          maxLength: 140
        suffix:
          type: string
          description: The suffix for the party's name.
          maxLength: 140
        alternate_full_name:
          type: string
          description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
          maxLength: 300
        full_name:
          type: string
          description: When the party is a person, the party's full name.
          maxLength: 300
    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
          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
          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:
          type: array
          items:
            $ref: '#/components/schemas/recipient_info'
          maxItems: 100
          description: The billing and shipping information. Includes name, email, address, phone and language.
        additional_recipients:
          type: array
          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.<blockquote><strong>Note:</strong> Valid values are email addresses in the `additional_recipients` value associated with the invoice.</blockquote>'
          items:
            $ref: '#/components/schemas/email_address'
        items:
          type: array
          description: An array of invoice line item information.
          maxItems: 100
          items:
            $ref: '#/components/schemas/item'
        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:
          description: The due amount, which is the balance amount outstanding after payments.
          $ref: '#/components/schemas/money'
          readOnly: true
        gratuity:
          description: The amount paid by the payer as gratuity to the invoicer.
          $ref: '#/components/schemas/money'
          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:
          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'
    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:
            description: The flow variation that created this invoice.
            $ref: '#/components/schemas/invoice_creation_flow'
            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.
    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'
    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:
          type: array
          description: An array of refund details for the invoice. Includes the refund type, date, amount, and method.
          maxItems: 100
          items:
            $ref: '#/components/schemas/refund_detail'
          readOnly: true
    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
    error_link_description:
      title: Link Description
      description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
      type: object
      required:
      - href
      - rel
      properties:
        href:
          description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
          type: string
          minLength: 0
          maxLength: 20000
          pattern: ^.*$
        rel:
          description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).
          type: string
          minLength: 0
          maxLength: 100
          pattern: ^.*$
        method:
          description: The HTTP method required to make the related call.
          type: string
          minLength: 3
          maxLength: 7
          pattern: ^[A-Z]*$
          enum:
          - CONNECT
          - DELETE
          - GET
          - HEAD
          - OPTIONS
          - PATCH
          - POST
          - PUT
    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*.
    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:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/).
          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.
    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
        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
    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.
    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.
            default: PayPal system template
            maxLength: 30
    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: 127
          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 <code>term_type</code> or <code>due_date</code>.
          metadata:
            $ref: '#/components/schemas/metadata'
            description: The audit metadata. Captures all invoicing actions on create, send, update, and cancel.
            readOnly: true
    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.<blockquote><strong>Note:</strong> This feature is not available for users in `India`, `Brazil`, or `Israel`.</blockquote>
          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`.
    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 post office (PO) number.
          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.
          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.
          maxLength: 4000
        memo:
          type: string
          description: A private bookkeeping memo for the user.
          maxLength: 500
        attachments:
          type: array
          description: An array of PayPal IDs for the files that are attached to an invoice.
          maximum: 5
          items:
            $ref: '#/components/schemas/file_reference'
    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_500'
      - $ref: '#/components/schemas/error_503'
    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. <blockquote><strong>Note: The regular expression provides guidance but does not reject all invalid dates.</strong></blockquote><br/>Minimum length: 20.<br/>Maximum length: 64<br/>Pattern: <code>^[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})$</code>'
      required:
      - start
      - end
    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.
    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:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/).
          maxLength: 32
          pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
      required:
      - currency_code
      - value
    search_data:
      type: object
      title: Search Data
      description: The invoice search parameters.
      properties:
        recipient_email:
          type: string
          maxLength: 254
          description: Filters the search by the email address.
        recipient_first_name:
          type: string
          description: Filters the search by the recipient first name.
          maxLength: 140
        recipient_last_name:
          type: string
          description: Filters the search by the recipient last name.
          maxLength: 140
        recipient_business_name:
          type: string
          description: Filters the search by the recipient business name.
          maxLength: 300
        invoice_number:
          type: string
          maxLength: 25
          description: Filters the search by the invoice number.
        status:
          type: array
          description: An array of status values.
          items:
            $ref: '#/components/schemas/invoice_status'
          maxItems: 5
        reference:
          type: string
          description: The reference data, such as a PO number.
          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.
          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:<ul><li><code>true</code>. Response lists only merchant-archived invoices.</li><li><code>false</code>. Response lists only unarchived invoices.</li><li><code>null</code>. Response lists all invoices.</li></ul>
        fields:
          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 <code>items</code>, <code>payments</code>, <code>refunds</code>, <code>additional_recipients_info</code>, and <code>attachments</code>.
          type: array
          items:
            type: string
            description: The name of the field.
    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.<blockquote><strong>Note:</strong> This feature is not available for users in `Hong Kong`, `Taiwan`, `India`, or `Japan`.</blockquote>
          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.
    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
    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.
    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:<ul><li>The postal sorting code for Guernsey and many French territories, such as French Guiana.</li><li>The fine-grained administrative levels in China.</li></ul>
          maxLength: 100
        admin_area_3:
          type: string
          description: A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is:<ul><li>Brazil. Suburb, bairro, or neighborhood.</li><li>India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.</li></ul>
          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:<ul><li>UK. A county.</li><li>US. A state.</li><li>Canada. A province.</li><li>Japan. A prefecture.</li><li>Switzerland. A kanton.</li></ul>
          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:
          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.<br/>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, <code>Craven House</code>.
              maxLength: 100
            sub_building:
              type: string
              description: The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
              maxLength: 100
      required:
      - country_code
    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:
          description: The payment type in an invoicing flow which can be PayPal or an external cash or check payment.
          $ref: '#/components/schemas/payment_type'
          readOnly: true
        payment_id:
          type: string
          description: The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type.
          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*.
        method:
          description: The payment mode or method through which the invoicer can accept the payment.
          $ref: '#/components/schemas/payment_method'
        note:
          type: string
          description: A note associated with an external cash or check payment.
          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
    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
    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'
    payment_method:
      type: string
      title: Payment Method
      description: The payment mode or method through which the invoicer can accept the payments.
      enum:
      - BANK_TRANSFER
      - CASH
      - CHECK
      - CREDIT_CARD
      - DEBIT_CARD
      - PAYPAL
      - WIRE_TRANSFER
      - OTHER
    currency_code:
      description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.
      type: string
      format: ppaas_common_currency_code_v2
      minLength: 3
      maxLength: 3
    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.
    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.
    country_code:
      type: string
      description: The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) that identifies the country or region.<blockquote><strong>Note:</strong> The country code for Great Britain is <code>GB</code> and not <code>UK</code> 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.</blockquote>
      format: ppaas_common_country_code_v2
      maxLength: 2
      minLength: 2
      pattern: ^([A-Z]{2}|C2)$
    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
        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
      required:
      - name
      - percent
    payment_type:
      type: string
      title: Payment Type
      description: The payment type. Can be PayPal or an external payment. Includes cash or a check.
      enum:
      - PAYPAL
      - EXTERNAL
    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'
    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/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:
            type: array
            items:
              $ref: '#/components/schemas/phone_detail'
            description: The invoice recipient's phone numbers. Extension number is not supported.
          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.
    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
    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/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:
            type: array
            items:
              $ref: '#/components/schemas/phone_detail'
            description: An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice.
          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
    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'
    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
    unit_of_measure:
      type: string
      description: The unit of measure for the invoiced item.
      enum:
      - QUANTITY
      - HOURS
      - AMOUNT
    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]+))$
    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
    email_address:
      type: string
      description: The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
      format: ppaas_common_email_address_v2
      minLength: 3
      maxLength: 254
      pattern: ^.+@[^"\-].+$
    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.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
      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})$
    refund_detail:
      type: object
      title: Refund Detail
      description: The refund details of the invoice. Includes the refund type, date, amount, and method.
      properties:
        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.
          $ref: '#/components/schemas/payment_type'
          readOnly: true
        refund_id:
          type: string
          description: The ID for a PayPal payment transaction. Required for the `PAYPAL` payment type.
          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:
          description: The payment mode or method through which the invoicer can accept the payments.
          $ref: '#/components/schemas/payment_method'
      required:
      - method
    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. <blockquote><strong>Note:</strong> Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next</blockquote>
          readOnly: true
        total_items:
          type: integer
          description: The total number of invoices that match the search criteria.<blockquote><strong>Note:</strong> Clients MUST NOT assume that the value of <code>total_items</code> is constant. The value MAY change from one request to the next.</blockquote>
          readOnly: true
        items:
          type: array
          description: The list of invoices that match the search criteria.
          readOnly: true
          items:
            $ref: '#/components/schemas/invoice'
        links:
          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'
    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.
          maxLength: 50
        amount:
          $ref: '#/components/schemas/money'
          description: The custom amount value. Value is from `-1000000` to `1000000`. Supports up to two decimal places.
  parameters:
    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
    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
    total_required:
      name: total_required
      in: query
      description: Indicates whether the to show <code>total_pages</code> and <code>total_items</code> in the response.
      schema:
        type: boolean
        default: false
  examples:
    search_data:
      value:
        total_amount_range:
          lower_amount:
            currency_code: USD
            value: '50.00'
          upper_amount:
            currency_code: USD
            value: '50.00'
        invoice_date_range:
          start: '2018-06-01'
          end: '2018-06-21'
  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/subscriptions: Manage plan & subscription
externalDocs:
  url: https://developer.paypal.com/docs/api/subscriptions/v1/