openapi: 3.2.0
info:
  title: Invoicing
  description: <blockquote><strong>Deprecation notice:</strong> The
    <code>/v1/invoices</code> endpoint is deprecated. Use the
    <code>/v2/invoices</code> endpoint instead. For details, see <a
    href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
    Integration</a>.</blockquote>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 <a
    href="/docs/invoicing/">Invoicing Overview</a> and the <a
    href="docs/archive/invoicing/integrate/">Invoicing Integration Guide</a>.
  version: "1.13"
deprecated: true
paths:
  /v1/invoicing/invoices:
    post:
      summary: Create draft invoice
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Creates a draft invoice. To move the
        invoice from a draft to payable state, you must <a
        href="/docs/api/invoicing/v1/#invoices_send">send the
        invoice</a>.<br/><br/>In the JSON request body, include invoice details
        including merchant information. The <code>invoice</code> object must
        include an <code>items</code> array.<blockquote><strong>Note:</strong>
        The merchant that you specify in an invoice must have a PayPal account
        in good standing.</blockquote>.
      operationId: invoice.create
      responses:
        "201":
          description: A successful request returns the HTTP `201 Created` status code and
            a JSON response body that shows invoice details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/invoice"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      requestBody:
        $ref: "#/components/requestBodies/invoice"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
    get:
      summary: List invoices
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Lists invoices. To filter the invoices that
        appear in the response, you can specify one or more optional query
        parameters.
      operationId: invoice.get_all
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that lists invoices with details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/invoices"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/total_count_required"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/search:
    post:
      summary: Search for invoices
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Searches for invoices that match search
        criteria. If you pass multiple criteria, the response lists invoices
        that match all criteria.
      operationId: invoice.search
      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"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/search"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - search
  /v1/invoicing/invoices/{invoice_id}/send:
    post:
      summary: Send invoice
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Sends an invoice, by ID, to a customer. To
        suppress the merchant's email notification, set the `notify_merchant`
        query parameter to `false`.<blockquote><strong>Note:</strong> After you
        send an invoice, you cannot resend it.</blockquote>
      operationId: invoice.send
      responses:
        "202":
          description: A successful request returns the HTTP `202 Accepted` status code
            with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
        - $ref: "#/components/parameters/notify_merchant"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/schedule:
    post:
      summary: Schedule invoice
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Schedules an invoice, by ID, to send on a
        future date. At 07:00 on that date in the preferred time zone of the
        merchant's PayPal account profile, PayPal emails an invoice notification
        to the merchant and the customer, adds an online payment button to the
        customer’s view of the invoice, and updates the invoice status to
        <code>SENT</code>.<blockquote><strong>Note:</strong> To change the
        scheduled date, adjust the invoice date and <a
        href="/docs/api/invoicing/v1/#invoices_update">update invoice</a>. To
        send the invoice immediately, update the invoice date to today or to a
        date in the past.</blockquote>
      operationId: invoice.schedule
      responses:
        "202":
          description: A successful request returns the HTTP `202 Accepted` status code
            and a JSON response body with a link to the invoice .
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/remind:
    post:
      summary: Send invoice reminder
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Sends a reminder to the payer about an
        invoice, by ID. In the JSON request body, include a `notification`
        object that defines the subject of the reminder and other details.
      operationId: invoice.remind
      responses:
        "202":
          description: A successful request returns the HTTP `202 Accepted` status code
            with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/notification"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/cancel:
    post:
      summary: Cancel sent invoice
      description: '<blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Cancels a sent invoice, by ID, and,
        optionally, sends a notification about the cancellation to the payer,
        merchant, and CC: emails.'
      operationId: invoice.cancel
      responses:
        "204":
          description: A successful request returns the HTTP `204 No Content` status code
            with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/cancel-notification"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/record-payment:
    post:
      summary: Mark invoice as paid
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Marks the status of an invoice, by ID, as
        paid.
      operationId: invoice.record-payment
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code with no
            JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/payment-detail"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/record-refund:
    post:
      summary: Mark invoice as refunded
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Marks the status of an invoice, by ID, as
        refunded.
      operationId: invoice.record-refund
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code with no
            JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/refund-detail"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}:
    get:
      summary: Show invoice details
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Shows details for an invoice, by ID.
      operationId: invoice.get
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that shows invoice details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/invoice"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
    put:
      summary: Update invoice
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Fully updates an invoice, by ID. In the
        JSON request body, include a complete `invoice` object. This call does
        not support partial updates.
      operationId: invoice.update
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that shows invoice details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/invoice"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
        - $ref: "#/components/parameters/notify_merchant"
      requestBody:
        $ref: "#/components/requestBodies/invoice"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
    delete:
      summary: Delete draft invoice
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Deletes invoices in the <code>DRAFT</code>
        or <code>SCHEDULED</code> state, by ID. For invoices that have already
        been sent, you can <a
        href="/docs/api/invoicing/v1/#invoices_cancel">cancel the invoice</a>.
        After you delete a draft or scheduled invoice, you can no longer use it
        or show its details. However, you can reuse its invoice number.
      operationId: invoice.delete
      responses:
        "204":
          description: A successful request returns the HTTP `204 No Content` status code
            with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/payment-records/{transaction_id}:
    delete:
      summary: Delete external payment
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Deletes an external payment, by invoice ID
        and transaction ID.
      operationId: invoice.delete_external_payment
      responses:
        "204":
          description: A successful request returns the HTTP `204 No Content` status code
            with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
        - $ref: "#/components/parameters/transaction_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/refund-records/{transaction_id}:
    delete:
      summary: Delete external refund
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Deletes an external refund, by invoice ID
        and transaction ID.
      operationId: invoice.delete_external_refund
      responses:
        "204":
          description: A successful request returns the HTTP `204 No Content` status code
            with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
        - $ref: "#/components/parameters/transaction_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/{invoice_id}/qr-code:
    get:
      summary: Generate QR code
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Generates a QR code for an invoice, by ID.
        The QR code is a PNG image in <a
        href="https://www.base64encode.org/">Base64-encoded</a> format that
        corresponds to the invoice ID. You can generate a QR code for an invoice
        and add it to a paper or PDF invoice. When customers use their mobile
        devices to scan the QR code, they are redirected to the PayPal mobile
        payment flow where they can view the invoice and pay online with PayPal
        or a credit card. Before you get a QR code, you must <a
        href="#invoices_create">create an invoice</a> and <a
        href="#invoices_send">send an invoice</a> to move the invoice from a
        draft to payable state. Do not include an email address if you do not
        want the invoice emailed.
      operationId: invoice.qr_code
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that shows the QR code as a PNG image.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/qr_code"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/invoice_id"
        - $ref: "#/components/parameters/width"
        - $ref: "#/components/parameters/height"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/invoices/next-invoice-number:
    post:
      summary: Generate invoice number
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Generates the next invoice number that is
        available to the merchant. The next invoice number uses the prefix and
        suffix from the last invoice number and increments the number by one.
        For example, the next invoice number after `INVOICE-1234` is
        `INVOICE-1235`.
      operationId: invoice.next_invoice_number
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that shows the next invoice number.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/invoice_number"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - invoices
  /v1/invoicing/templates:
    post:
      summary: Create template
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Creates an invoice template. You can use
        details from this template to create an invoice. You can create up to 50
        templates.<blockquote><strong>Note:</strong> Every merchant starts with
        three PayPal system templates that are optimized for the unit type
        billed. The template includes `Quantity`, `Hours`, and
        `Amount`.</blockquote>
      operationId: template.create
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that shows template details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/template"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      requestBody:
        $ref: "#/components/requestBodies/template"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - templates
    get:
      summary: List templates
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Lists merchant-created templates with
        associated details. The associated details include the email addresses,
        postal addresses, and phone numbers from the user's PayPal
        profile.<br/>The user can select which values to show in the business
        information section of their template.
      operationId: template.get_templates
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that lists invoices.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/templates"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/fields"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - templates
  /v1/invoicing/templates/{template_id}:
    get:
      summary: Show template details
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Shows details for a template, by ID.
      operationId: template.get
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that shows template details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/template"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/template_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - templates
    delete:
      summary: Delete template
      description: Deletes a template, by ID.
      operationId: template.delete
      responses:
        "204":
          description: A successful request returns the HTTP `204 No Content` status code
            with no JSON response body.
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/template_id"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - templates
    put:
      summary: Update template
      description: <blockquote><strong>Deprecation notice:</strong> The
        <code>/v1/invoices</code> endpoint is deprecated. Use the
        <code>/v2/invoices</code> endpoint instead. For details, see <a
        href="/docs/invoicing/basic-integration/">PayPal Invoicing Basic
        Integration</a>.</blockquote>Updates a template, by ID. In the JSON
        request body, specify a complete `template` object. The update method
        does not support partial updates.
      operationId: template.update
      responses:
        "200":
          description: A successful request returns the HTTP `200 OK` status code and a
            JSON response body that shows template details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/template"
        default:
          description: The error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
      parameters:
        - $ref: "#/components/parameters/template_id"
      requestBody:
        $ref: "#/components/requestBodies/template"
      security:
        - Oauth2:
            - https://uri.paypal.com/services/invoicing
      tags:
        - templates
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 mark invoices as fully or partially paid, or as
      refunded. Lastly, you can create QR codes for invoices that can be
      scanned, viewed, and paid by a mobile phone.
  - name: templates
    description: Use the `/templates` resource to create, list, show details for,
      update, and delete invoice templates. The template API is useful when
      creating a third-party invoicing application. For instance, a business can
      create a template with predefined invoice data. Later, the business can
      select the template to populate the invoice
      data.<blockquote><strong>Note:</strong> To upload a logo to display on an
      invoice, you can use the <strong>Template Settings</strong> dashboard to
      <a href="https://www.paypal.com/invoice/settings/templates">create a
      template</a>. Then, use the URI of that logo when you create an
      invoice.</blockquote>
  - name: files
    description: Use the `/files` resource to upload a file attachment for an invoice.
  - name: group-invoices
    description: Use the `/group-invoices` resource to create a batch, or group of,
      invoices.
  - name: search
    description: Use the `/search` resource to search for invoices.
  - name: summaries
    description: Use the `/summaries` resource to list invoice summary information,
      including counts. The list is grouped by invoice status.
externalDocs:
  url: /docs/invoicing/
servers:
  - url: https://api-m.sandbox.paypal.com
    description: PayPal API Sandbox
components:
  requestBodies:
    invoice:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/invoice"
    template:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/template"
  securitySchemes:
    Oauth2:
      type: oauth2
      description: Oauth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /api/oauth-proxy
          scopes:
            https://uri.paypal.com/services/invoicing: Manage invoice resource.
  responses:
    default:
      description: The default response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/error_default"
  schemas:
    additionalItems:
      type: object
      title: Additional Items
      description: Any additional items.
    address:
      type: object
      title: Address
      description: The address, which is either a billing address or shipping address
        in a payment.
      properties:
        line1:
          type: string
          description: The first line of the address. For example, number or street.
        line2:
          type: string
          description: The second line of the address. For example, suite or apartment
            number.
        city:
          type: string
          description: The city name.
        country_code:
          type: string
          description: The [two-character ISO 3166-1
            code](/api/rest/reference/country-codes/) that identifies the
            country or region.<blockquote><strong>Note:</strong> The country
            code for Great Britain is `GB` and not `UK` as is used in that
            country's top-level domain names. Use the `C2` country code for
            China worldwide for comparable uncontrolled price (CUP) method, bank
            card, and cross-border transactions.</blockquote>
        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).
        state:
          type: string
          description: "The [code](/api/rest/reference/state-codes/) for a US state or the
            equivalent for other countries. Required for transactions if the
            address is in one of these countries:
            [Argentina](/api/rest/reference/state-codes/#argentina),
            [Brazil](/api/rest/reference/state-codes/#brazil),
            [Canada](/api/rest/reference/state-codes/#canada),
            [China](/api/rest/reference/state-codes/#china),
            [India](/api/rest/reference/state-codes/#india),
            [Italy](/api/rest/reference/state-codes/#italy),
            [Japan](/api/rest/reference/state-codes/#japan),
            [Mexico](/api/rest/reference/state-codes/#mexico),
            [Thailand](/api/rest/reference/state-codes/#thailand), or [United
            States](/api/rest/reference/state-codes/#usa). Maximum length is 40
            single-byte characters."
        phone:
          type: string
          format: phone
          description: The phone number, in its canonical international [E.164 numbering
            plan format](https://www.itu.int/rec/T-REC-E.164/en).
      required:
        - line1
        - city
        - country_code
    address_list:
      type: array
      description: An array of postal addresses in the user's PayPal profile.
      items:
        $ref: "#/components/schemas/address"
    allOf:
      type: object
      title: All Of Item
      description: A sub-schema against which the data must validate.
    allOf_list:
      type: array
      description: An array of sub-schemas. The data must validate against all sub-schemas.
      items:
        $ref: "#/components/schemas/allOf"
    anyOf:
      type: object
      title: Any Of Item
      description: A sub-schema against which the data must validate.
    anyOf_list:
      type: array
      description: An array of sub-schemas. The data must validate against one or more
        sub-schemas.
      items:
        $ref: "#/components/schemas/anyOf"
    billing-info:
      type: object
      title: Billing Information
      description: The billing information for the invoice recipient.
      properties:
        email:
          type: string
          format: email
          description: The invoice recipient email address. If you omit this value, the
            invoice is payable and a notification email is not sent.
          maxLength: 260
        phone:
          $ref: "#/components/schemas/phone"
          description: The invoice recipient's phone number.
        first_name:
          type: string
          description: The invoice recipient's first name.
          maxLength: 30
        last_name:
          type: string
          description: The invoice recipient's last name.
          maxLength: 30
        business_name:
          type: string
          description: The invoice recipient's business name.
          maxLength: 100
        address:
          $ref: "#/components/schemas/address"
          description: The invoice recipient's billing address.
        language:
          type: string
          description: The language in which the invoice recipient's email appears. Used
            only when the recipient does not have a PayPal account.<br/>If you
            omit the language and the recipient does not have a PayPal account,
            the email is sent in the language of the merchant's PayPal account.
          enum:
            - da_DK
            - de_DE
            - en_AU
            - en_GB
            - en_US
            - es_ES
            - es_XC
            - fr_CA
            - fr_FR
            - fr_XC
            - he_IL
            - id_ID
            - it_IT
            - ja_JP
            - nl_NL
            - no_NO
            - pl_PL
            - pt_BR
            - pt_PT
            - ru_RU
            - sv_SE
            - th_TH
            - tr_TR
            - zh_CN
            - zh_HK
            - zh_TW
            - zh_XC
        additional_info:
          type: string
          description: Any additional information about the recipient.
          maxLength: 40
    billing-info_list:
      type: array
      description: An array of billing information for the invoice
        recipient.<blockquote><strong>Note:</strong> This value is an array with
        only one element.</blockquote>
      minItems: 1
      maxItems: 1
      items:
        $ref: "#/components/schemas/billing-info"
    cancel-notification:
      type: object
      title: Cancel Notification
      description: Cancels an email or SMS notification.
      properties:
        subject:
          type: string
          description: The subject of the notification. If left blank we include a generic
            subject.
        note:
          type: string
          description: A note to the payer.
        send_to_merchant:
          type: boolean
          description: Indicates whether to send the notification to the merchant.
          default: true
        send_to_payer:
          type: boolean
          description: Indicates whether to send the notification to the payer.
          default: true
        cc_emails:
          $ref: "#/components/schemas/definitions-cc_emails_list"
    cc_emails:
      type: string
      description: "A CC: email to which to send a notification email."
      minLength: 3
      maxLength: 254
      pattern: ^.+@[^"\-].+$
    cc_emails_list:
      type: array
      description: "An array of one or more CC: emails to which to send notification
        emails. If you omit this parameter, the API sends notification emails to
        all CC: email addresses that are part of the
        invoice.<blockquote><strong>Note:</strong> Valid values are email
        addresses in the `cc_info` array of the invoice.</blockquote>"
      maxItems: 100
      items:
        $ref: "#/components/schemas/cc_emails"
    currency:
      type: object
      title: Currency
      description: The currency and amount for a financial transaction, such as a
        balance or payment due.
      properties:
        currency:
          type: string
          description: The [three-character ISO-4217 currency
            code](/api/rest/reference/currency-codes/).
        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 - ISO
            4217](https://www.iso.org/iso-4217-currency-codes.html).
      required:
        - currency
        - value
    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.
      properties:
        label:
          type: string
          description: The custom amount label.
          maxLength: 50
        amount:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the custom value. Value is from
            `-1000000` to `1000000`. Supports up to two decimal places.
    definitions-billing-info_list:
      type: array
      description: The billing information of the invoice
        recipient.<blockquote><strong>Note:</strong> This value is an array with
        only one element.</blockquote>
      minItems: 1
      maxItems: 1
      items:
        $ref: "#/components/schemas/billing-info"
    definitions-cc_emails_list:
      type: array
      description: "An array of one or more CC: emails to which to send notification
        emails. If you omit this parameter, the API sends notification emails to
        all CC: email addresses that are part of the
        invoice.<blockquote><strong>Note:</strong> Additional email addresses
        are not supported.</blockquote>"
      maxItems: 100
      items:
        $ref: "#/components/schemas/cc_emails"
    definitions-file-attachment_list:
      type: array
      description: An array of PayPal file IDs for the files that are attached to an
        invoice. The maximum number of files is `5`.
      items:
        $ref: "#/components/schemas/file-attachment"
    definitions-invoice-item_list:
      type: array
      description: An array of invoice line item information. The maximum items for an
        invoice is `100`.
      maxItems: 100
      items:
        $ref: "#/components/schemas/invoice-item"
    dependencies:
      type: object
      title: Dependencies
      description: Any Dependencies.
    discount:
      type: object
      title: Discount
      description: The discount as a percent or an amount value. For example, to
        specify 10%, enter `10`. Alternatively, to specify an amount of 5, enter
        `5`.
      properties:
        percent:
          type: number
          description: The discount as a percentage value. Value is from `0` to `100`.
            Supports up to five decimal places.
        amount:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the invoice-level discount. Value is
            from `0` to `1000000`. Supports up to two decimal places.
    email:
      title: Email
      type: string
      format: email
      description: The participant's email address.
    email_list:
      type: array
      description: An array of email addresses to which PayPal sends a copy of the invoice.
      items:
        $ref: "#/components/schemas/email"
    emails:
      description: An email in the user's PayPal profile.
      type: string
      minLength: 3
      maxLength: 254
      pattern: ^.+@[^"\-].+$
    emails_list:
      type: array
      description: An array of email addresses in the user's PayPal profile.
      items:
        $ref: "#/components/schemas/emails"
    error:
      type: object
      title: Error
      description: The error information.
      properties:
        name:
          type: string
          description: The human-readable, unique name of the error.
          readOnly: true
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
          readOnly: true
        message:
          type: string
          description: The message that describes the error.
          readOnly: true
        information_link:
          type: string
          description: The URI to detailed information related to this error for the
            developer.
          readOnly: true
        details:
          $ref: "#/components/schemas/error_details_list"
      required:
        - name
        - message
        - information_link
    error_400:
      type: object
      title: Bad Request Error
      description: Request is not well-formed, syntactically incorrect, or violates schema.
      properties:
        name:
          type: string
          enum:
            - INVALID_REQUEST
        message:
          type: string
          enum:
            - Request is not well-formed, syntactically incorrect, or violates
              schema.
        details:
          type: array
          items:
            $ref: "#/components/schemas/error_details"
        debug_id:
          type: string
          description: The PayPal internal ID. Used for correlation purposes.
        links:
          description: An array of request-related [HATEOAS
            links](https://en.wikipedia.org/wiki/HATEOAS).
          type: array
          minItems: 0
          maxItems: 10000
          items:
            $ref: "#/components/schemas/error_link_description"
    error_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_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_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_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"
      examples:
        - 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
    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"
      examples:
        - name: SERVICE_UNAVAILABLE
          message: Service Unavailable.
          debug_id: 90957fca61718
          information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE
    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"
    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_details-2:
      type: object
      title: Error Details
      description: The error details. Required for client-side `4XX` errors.
      properties:
        field:
          type: string
          description: The name of the field that caused the error.
        issue:
          type: string
          description: The reason for the error.
      required:
        - field
        - issue
    error_details_list:
      type: array
      description: An array of additional details for the error.
      readOnly: true
      items:
        $ref: "#/components/schemas/error_details-2"
    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_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
    file-attachment:
      type: object
      title: File Attachment
      description: The file that is attached to an invoice or template.
      properties:
        name:
          type: string
          description: The name of the attached file.
        url:
          type: string
          format: uri
          description: The URL of the attached file. Use this URL to download the file.
    file-attachment_list:
      type: array
      description: An array of PayPal file IDs for the files that are attached to an
        invoice. You can attach up to five files.
      readOnly: true
      items:
        $ref: "#/components/schemas/file-attachment"
    invoice:
      title: Invoice
      type: object
      description: The invoice details.
      properties:
        id:
          type: string
          description: The ID of the invoice.
          readOnly: true
        number:
          type: string
          description: The invoice number. If you omit this value, the default is the
            number that the API automatically increments from the last number.
          maxLength: 25
        status:
          type: string
          description: "The invoice status. When you [search for
            invoices](/docs/api/invoicing/v1/#search_search), you must specify
            this value as an array. For example, `\"status\": [\"REFUNDED\"]`.
            The status indicates the phase of an invoice in its lifecycle. The
            status also indicates whether the invoice is unpaid, partially paid,
            fully paid, partially refunded, or fully refunded. An invoice
            payment can be either: <ul><li
            id=\"connected\"><p><strong>Connected</strong> to an invoice. The
            customer clicks <strong>Pay</strong> on the invoice to make a
            payment. The payment is automatically recorded.</p></li><li
            id=\"disconnected\"><p><strong>Disconnected</strong> from an
            invoice. The customer pays by check, wire transfer, or another
            method. The merchant manually records the
            payment.</p></li></ul><br/><a
            id=\"disconnected-refund\"></a>Similarly, an invoice refund can be
            <strong>disconnected</strong> from an invoice. The merchant refunds
            a payment by check, wire transfer, or another method and manually
            records the refund. This table lists the typical order through which
            an invoice moves through status values:
            <table><thead><tr><th>Status</th><th>Occurs
            when</th></tr></thead><tbody><tr><td><code>DRAFT</code></td><td><p>A
            merchant <a href=\"/docs/api/invoicing/v1/#invoices_create\">creates
            a draft invoice</a>.</p><blockquote><strong>Note:</strong> A
            customer cannot pay an invoice with this status. A customer cannot
            pay an invoice until it has a status of <code>SENT</code> or
            <code>UNPAID</code>.</blockquote></td></tr><tr><td><code>UNPAID</co\
            de></td><td><p>A merchant chooses to suppress the PayPal email
            notification when he or she sends the invoice through the <a
            href=\"/docs/api/invoicing/v1/#invoices_send\">API</a> or the <a
            href=\"https://www.paypal.com/invoice/create\">Create Invoice</a>
            page, and then manually sends the invoice link in his or her own
            email.</p><p>To send an invoice without email notification, the
            merchant either:</p><ul><li><p>Sets the <code>notify_merchant</code>
            and <code>notify_customer</code> query parameters to
            <code>false</code> when he or she <a
            href=\"/docs/api/invoicing/v1/#invoices_send\">sends the
            invoice</a>.</p></li><li><p>Selects <strong>Share link
            myself</strong> from the <strong>Send</strong> menu when he or she
            sends the invoice through the web UI <a
            href=\"https://www.paypal.com/invoice/create\">Create Invoice</a>
            page.</p></li></ul></td></tr><tr><td><code>SENT</code></td><td><p>A
            merchant accepts the default PayPal email notification when he or
            she sends the invoice through the <a
            href=\"/docs/api/invoicing/v1/#invoices_send\">API</a> or the <a
            href=\"https://www.paypal.com/invoice/create\">Create Invoice</a>
            page. PayPal automatically emails the invoice to the customer and a
            <strong>Pay</strong> button appears on the invoice, which enables
            the customer to pay the invoice. In a web app, the invoice appears
            as <code>Unpaid
            (sent)</code>.</p></td></tr><tr><td><code>SCHEDULED</code></td><td>\
            <p>A merchant <a
            href=\"/docs/api/invoicing/v1/#invoices_schedule\">schedules an
            invoice</a> to send on a future date. At 07:00 on that date in the
            preferred time zone of the merchant's PayPal account profile, PayPal
            emails an invoice notification to the merchant and the customer,
            adds an online payment button to the customer’s view of the invoice,
            and updates the invoice status to
            <code>SENT</code>.</li></ul></td></tr><tr><td><code>PARTIALLY_PAID<\
            /code></td><td><p>A customer makes a partial payment for the invoice
            through one of these methods:</p><ul><li><p>A customer makes a <a
            href=\"#disconnected\">disconnected partial payment</a> for the
            invoice and the merchant manually <a
            href=\"/docs/api/invoicing/v1/#invoices_record-payment\">marks the
            invoice as paid</a>.</p></li><li><p>A customer makes a <a
            href=\"#connected\">connected partial payment</a> for the
            invoice.</p></li></ul></td></tr><tr><td><code>PAYMENT_PENDING</code\
            ></td><td><p>A customer pays an invoice but the payment is pending
            for one of these reasons:</p><ul><li>The payment is an uncleared
            eCheck.</li><li>The merchant must either accept the payment before
            it clears or deny the payment.</li><li>PayPal risk is reviewing the
            payment.</li></ul><blockquote><strong>Note:</strong> Most payments
            never go into a payment-pending
            state.</blockquote></td></tr><tr><td><code>PAID</code></td><td><p>A
            customer fully pays the invoice through one of these
            methods:</p><ul><li><p>A customer makes a <a
            href=\"#connected\">connected full payment</a> for the
            invoice.</p></li><li><p>A customer makes a <a
            href=\"#connected\">connected partial payment</a> for the invoice.
            Then, the customer makes a <a href=\"#disconnected\">disconnected
            payment</a>, such as a check payment, to pay the balance of the
            invoice and the merchant manually marks the invoice as fully
            paid.</p></li></ul></td></tr><tr><td><code>MARKED_AS_PAID</code></t\
            d><td><p>A customer makes a <a href=\"#disconnected\">disconnected
            payment</a> for the balance of the invoice. The merchant manually
            marks the invoice as
            paid.</p></td></tr><tr><td><code>CANCELLED</code></td><td><p>A
            merchant or customer <a
            href=\"/docs/api/invoicing/v1/#invoices_cancel\">cancels a sent
            invoice</a>. You can cancel an invoice in <code>SENT</code> or
            <code>UNPAID</code>
            status.</p></td></tr><tr><td><code>REFUNDED</code></td><td><p>A
            merchant fully refunds an invoice through one these
            methods:</p><ul><li><p>A merchant makes a <a
            href=\"#connected\">connected full refund</a> for the
            invoice.</p></li><li><p>A merchant makes a <a
            href=\"#connected\">connected partial refund</a> for the invoice.
            Then, the merchant makes a <a
            href=\"#disconnected-refund\">disconnected refund</a>, such as a
            check payment, for the invoice balance and manually marks the
            invoice as fully
            refunded.</p></li></ul></td></tr><tr><td><code>PARTIALLY_REFUNDED</\
            code></td><td><p>A merchant partially refunds an invoice through one
            or both of these methods:</p><ul><li><p>A merchant makes a <a
            href=\"#disconnected\">disconnected partial refund</a>, such as a
            check payment, for the invoice and marks the invoice as partially
            refunded. To complete this action, the merchant must previously <a
            href=\"/docs/api/invoicing/v1/#invoices_record-payment\">mark the
            invoice as paid</a>.</p></li><li><p>A merchant makes a <a
            href=\"#connected\">connected partial refund</a> for a <a
            href=\"#connected\">connected partial
            payment</a>.</p></li></ul></td></tr><tr><td><code>MARKED_AS_REFUNDE\
            D</code></td><td><p>A merchant makes a <a
            href=\"#disconnected-refund\">disconnected refund</a>, such as a
            check payment, for the invoice balance and manually marks the
            invoice as fully refunded.</p><blockquote><strong>Note:</strong> A
            merchant can only mark a <a
            href=\"/docs/api/invoicing/v1/#invoices_record-payment\">marked-as-\
            paid invoice</a> as
            refunded.</blockquote></td></tr></tbody></table>"
          enum:
            - DRAFT
            - UNPAID
            - SENT
            - SCHEDULED
            - PARTIALLY_PAID
            - PAYMENT_PENDING
            - PAID
            - MARKED_AS_PAID
            - CANCELLED
            - REFUNDED
            - PARTIALLY_REFUNDED
            - MARKED_AS_REFUNDED
          readOnly: true
        merchant_info:
          $ref: "#/components/schemas/merchant-info"
          description: The merchant information, such as business name, email, address,
            and so on.
        billing_info:
          $ref: "#/components/schemas/billing-info_list"
        shipping_info:
          $ref: "#/components/schemas/shipping-info"
          description: The shipping information for the recipient of the invoice.
        cc_info:
          $ref: "#/components/schemas/participant_list"
        items:
          $ref: "#/components/schemas/invoice-item_list"
        invoice_date:
          type: string
          format: date
          description: The invoice date as specified by the sender, in [Internet date and
            time format](https://tools.ietf.org/html/rfc3339#section-5.6).
        payment_term:
          $ref: "#/components/schemas/payment-term"
          description: The payment due date of the invoice. If you include `due_date`, the
            `term_type` value is ignored.
        reference:
          type: string
          description: The reference data, such as PO number.
          maxLength: 60
        discount:
          $ref: "#/components/schemas/discount"
          description: The invoice level discount, as a percent or an amount value.
        shipping_cost:
          $ref: "#/components/schemas/shipping-cost"
          description: The shipping amount, as a percent or an amount value.
        custom:
          $ref: "#/components/schemas/custom-amount"
          description: The custom amount to apply to an invoice. If you include a label,
            you must include a custom amount.
        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 merchants in `India`, `Brazil`, or
            `Israel`.</blockquote>
          default: false
        minimum_amount_due:
          $ref: "#/components/schemas/currency"
          description: The minimum amount allowed for a partial payment. Valid only if
            `allow_partial_payment` is `true`.
        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: false
        tax_inclusive:
          type: boolean
          description: Indicates whether the unit price includes tax.
          default: false
        terms:
          type: string
          description: The general terms of the invoice.
          maxLength: 4000
        note:
          type: string
          description: A note to the invoice recipient. The note also appears on the
            invoice notification email.
          maxLength: 4000
        merchant_memo:
          type: string
          description: A private bookkeeping memo for the merchant.
          maxLength: 500
        logo_url:
          type: string
          format: uri
          description: The full URL to an external logo image. The logo must not be larger
            than 250 pixels wide by 90 pixels high. The logo must be stored on a
            secure server.
          maxLength: 4000
        total_amount:
          $ref: "#/components/schemas/currency"
          description: The total amount of the invoice.
          readOnly: true
        payments:
          $ref: "#/components/schemas/payment-detail_list"
        refunds:
          $ref: "#/components/schemas/refund-detail_list"
        metadata:
          $ref: "#/components/schemas/metadata"
          description: The audit information for the invoice.
          readOnly: true
        paid_amount:
          $ref: "#/components/schemas/payment-summary"
          description: The payment summary of the invoice. Includes the amount paid
            through PayPal and other sources.
          readOnly: true
        refunded_amount:
          $ref: "#/components/schemas/payment-summary"
          description: The payment summary of the invoice. Includes the amount refunded
            through PayPal and other sources.
          readOnly: true
        attachments:
          $ref: "#/components/schemas/file-attachment_list"
        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 merchants in `Hong Kong`, `Taiwan`, `India`, or
            `Japan`.</blockquote>
          default: false
        template_id:
          type: string
          description: This value is only used to determine the layout to display on the
            create or edit invoice experience, such as which fields to show and
            hide. It does not impact the view of the invoice that the customer
            receives.<blockquote><strong>Note:</strong> If you are just using
            the Invoicing APIs to create and send invoices, leave this field
            blank. The `template_id` is only needed if you use the Invoicing API
            to build a full invoicing solution that includes
            templates.</blockquote>
          default: PayPal system template
        links:
          $ref: "#/components/schemas/link_description_list"
      required:
        - merchant_info
    invoice-item:
      type: object
      title: Invoice Item
      description: The invoice line item information.
      properties:
        name:
          type: string
          description: The item name.
          maxLength: 200
        description:
          type: string
          description: The item description.
          maxLength: 1000
        quantity:
          type: number
          description: The item quantity. Value is from `-10000` to `10000`. Supports up
            to five decimal places.
        unit_price:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the item unit price. Value is from
            `-1000000` to `1000000`. Supports up to two decimal places.
        tax:
          $ref: "#/components/schemas/tax"
        date:
          type: string
          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* *z*.
          format: date
        discount:
          $ref: "#/components/schemas/discount"
          description: The item discount, as a percent or an amount value.
        unit_of_measure:
          type: string
          description: The unit of measure for the invoiced item. For `AMOUNT` the
            `unit_price` 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>
          enum:
            - QUANTITY
            - HOURS
            - AMOUNT
      required:
        - name
        - quantity
        - unit_price
    invoice-item_list:
      type: array
      description: An array of invoice line item information.
      maxItems: 100
      items:
        $ref: "#/components/schemas/invoice-item"
    invoice_list:
      type: array
      description: An array of invoice-level
        details.<blockquote><strong>Note:</strong> This array does not return
        item details for the invoice.</blockquote>
      items:
        $ref: "#/components/schemas/invoice"
    invoice_number:
      type: object
      title: Invoice Number
      description: The invoice number.
      properties:
        number:
          type: string
          description: The invoice number. If you omit this value from the request, the
            default is the number that the API automatically increments from the
            last number.
    invoices:
      type: object
      title: Invoices
      minItems: 1
      description: A list of merchant invoices. Can include the total invoices count
        and HATEOAS links for navigation.
      properties:
        total_count:
          type: integer
          description: The total number of invoices that match the search criteria.
          readOnly: true
        invoices:
          $ref: "#/components/schemas/invoice_list"
        links:
          $ref: "#/components/schemas/link_description_list"
    items:
      type: object
      title: Items
      description: An item.
    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.
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
        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).
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
        method:
          type: string
          description: The HTTP method required to make the related call.
          enum:
            - GET
            - POST
            - PUT
            - DELETE
            - HEAD
            - CONNECT
            - OPTIONS
            - PATCH
          oneOf:
            - type: string
              enum:
                - GET
              description: The HTTP GET method.
            - type: string
              enum:
                - POST
              description: The HTTP POST method.
            - type: string
              enum:
                - PUT
              description: The HTTP PUT method.
            - type: string
              enum:
                - DELETE
              description: The HTTP DELETE method.
            - type: string
              enum:
                - HEAD
              description: The HTTP HEAD method.
            - type: string
              enum:
                - CONNECT
              description: The HTTP CONNECT method.
            - type: string
              enum:
                - OPTIONS
              description: The HTTP OPTIONS method.
            - type: string
              enum:
                - PATCH
              description: The HTTP PATCH method.
        title:
          type: string
          description: The link title.
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
        mediaType:
          type: string
          description: The media type, as defined by [RFC
            2046](https://www.ietf.org/rfc/rfc2046.txt). Describes the link
            target.
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
        encType:
          type: string
          description: The media type in which to submit the request data.
          default: application/json
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
        schema:
          description: The schema that describes the request data.
          $ref: "#/components/schemas/link_schema"
        targetSchema:
          description: The schema that describes the link target.
          $ref: "#/components/schemas/link_schema"
    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"
    link_schema:
      type: object
      title: Link Schema
      description: The request data or link target.
      properties:
        additionalItems:
          $ref: "#/components/schemas/additionalItems"
        dependencies:
          $ref: "#/components/schemas/dependencies"
        items:
          $ref: "#/components/schemas/items"
        patternProperties:
          $ref: "#/components/schemas/patternProperties"
        properties:
          $ref: "#/components/schemas/properties"
        allOf:
          $ref: "#/components/schemas/allOf_list"
        anyOf:
          $ref: "#/components/schemas/anyOf_list"
        oneOf:
          $ref: "#/components/schemas/oneOf_list"
        not:
          $ref: "#/components/schemas/not"
        links:
          $ref: "#/components/schemas/links_list"
        fragmentResolution:
          type: string
          description: The fragment resolution.
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
        media:
          $ref: "#/components/schemas/media"
        pathStart:
          type: string
          format: uri
          description: To apply this schema to the instances' URIs, start the URIs with
            this value.
          minLength: 0
          maxLength: 2147483647
    links:
      type: object
      title: Link
      description: A link.
      readOnly: true
    links_list:
      type: array
      description: An array of links.
      readOnly: true
      items:
        $ref: "#/components/schemas/links"
    media:
      type: object
      title: Media
      description: The media type and context-encoding scheme.
      properties:
        type:
          type: string
          description: "The media type. See [Multipurpose Internet Mail Extensions (MIME)
            Part Two: Media Types](https://tools.ietf.org/html/rfc2046)."
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
        binaryEncoding:
          type: string
          description: "The content-encoding scheme. See [Multipurpose Internet Mail
            Extensions (MIME) Part One: Format of Internet Message
            Bodies](https://tools.ietf.org/html/rfc2045)."
          minLength: 0
          maxLength: 2147483647
          pattern: ^[\S\s]*$
    merchant-info:
      type: object
      title: Merchant Information
      description: The merchant business information that appears on the invoice.
      properties:
        email:
          type: string
          format: email
          description: The merchant email address. This email must be listed in the
            merchant's PayPal profile.<br/>If you omit this value, notifications
            are sent from and to the primary email address but do not appear on
            the invoice.
          maxLength: 260
        business_name:
          type: string
          description: The merchant's business name.
          maxLength: 100
        first_name:
          type: string
          description: The merchant's first name.
          maxLength: 256
        last_name:
          type: string
          description: The merchant's last name.
          maxLength: 256
        address:
          $ref: "#/components/schemas/address"
          description: The merchant's address.
        phone:
          $ref: "#/components/schemas/phone"
          description: The merchant's phone number.
        fax:
          $ref: "#/components/schemas/phone"
          description: The merchant's fax number.
        website:
          type: string
          format: uri
          description: The merchant's website.
          maxLength: 2048
        tax_id:
          type: string
          description: The merchant's tax ID.
          maxLength: 100
        additional_info:
          type: string
          description: Any additional information, such as business hours.
          maxLength: 40
    metadata:
      type: object
      title: Metadata
      description: The audit metadata.
      properties:
        created_date:
          type: string
          format: 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
        cancelled_date:
          type: string
          format: 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
        last_updated_date:
          type: string
          format: 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
        first_sent_date:
          type: string
          format: 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_date:
          type: string
          format: 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
        payer_view_url:
          type: string
          format: uri
          description: The URL for the payer's view of the invoice.
          readOnly: true
    not:
      type: object
      title: Not
      description: Not.
    notification:
      type: object
      title: Notification
      description: The email or SMS notification.
      properties:
        subject:
          type: string
          description: The subject of the notification. Default is a generic subject.
        note:
          type: string
          description: A note to the payer.
        send_to_merchant:
          type: boolean
          description: Indicates whether to send a copy of the email to the merchant.
          default: true
        cc_emails:
          $ref: "#/components/schemas/cc_emails_list"
    oneOf:
      type: object
      title: One Of Item
      description: A sub-schema against which the data must validate.
    oneOf_list:
      type: array
      description: An array of sub-schemas. The data must validate against one sub-schema.
      items:
        $ref: "#/components/schemas/oneOf"
    participant:
      type: object
      title: Participant
      description: The participant information.
      properties:
        email:
          type: string
          format: email
          description: The email address of the person who receives a copy of the invoice.
          maxLength: 260
      required:
        - email
    participant_list:
      type: array
      description: An array of email addresses to which PayPal sends a copy of the invoice.
      items:
        $ref: "#/components/schemas/participant"
    patternProperties:
      type: object
      title: Pattern Properties
      description: The pattern properties.
    payment-detail:
      type: object
      title: Payment Detail
      description: The payment details.
      properties:
        type:
          type: string
          description: The payment type in an invoicing flow. The [record
            refund](/docs/api/invoicing/v1/#invoices_record-refund) method
            supports the `EXTERNAL` refund type. The `PAYPAL` refund type is
            supported for backward compatibility.
          enum:
            - PAYPAL
            - EXTERNAL
          readOnly: true
        transaction_id:
          type: string
          description: The ID for a PayPal payment transaction. Required for the `PAYPAL`
            payment type.
          readOnly: true
        transaction_type:
          type: string
          description: The transaction type.
          enum:
            - SALE
            - AUTHORIZATION
            - CAPTURE
          readOnly: true
        date:
          type: string
          description: The date when the invoice was paid, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6).
          format: date-time
        method:
          type: string
          description: The payment mode or method.
          enum:
            - BANK_TRANSFER
            - CASH
            - CHECK
            - CREDIT_CARD
            - DEBIT_CARD
            - PAYPAL
            - WIRE_TRANSFER
            - OTHER
        note:
          type: string
          description: A note associated with the payment.
        amount:
          $ref: "#/components/schemas/currency"
          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.
      required:
        - method
    payment-detail_list:
      type: array
      description: An array of payment details for the invoice.
      maxItems: 1
      items:
        $ref: "#/components/schemas/payment-detail"
      readOnly: true
    payment-summary:
      type: object
      title: Payment Summary
      description: The payment and refund summary.
      properties:
        paypal:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the total paid or refunded through PayPal.
          readOnly: true
        other:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the total paid or refunded through other
            sources.
          readOnly: true
    payment-term:
      type: object
      title: Payment Term
      description: The payment term of the invoice. If you specify `term_type`, you
        cannot specify `due_date`, and vice versa.
      properties:
        term_type:
          type: string
          description: The term when the invoice payment is due.
          enum:
            - DUE_ON_RECEIPT
            - DUE_ON_DATE_SPECIFIED
            - NET_10
            - NET_15
            - NET_30
            - NET_45
            - NET_60
            - NET_90
            - NO_DUE_DATE
        due_date:
          type: string
          format: date
          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* *z*.
    phone:
      type: object
      title: Phone
      description: The phone number.
      properties:
        country_code:
          type: string
          description: The country code portion of the phone number, in [E.164
            format](https://www.itu.int/rec/T-REC-E.164-201011-I).
          minLength: 1
          maxLength: 3
          pattern: ^[0-9]{1,3}?$
        national_number:
          type: string
          description: The in-country phone number, in [E.164
            format](https://www.itu.int/rec/T-REC-E.164-201011-I).
          minLength: 1
          maxLength: 14
          pattern: ^[0-9]{1,14}?$
    phone_list:
      type: array
      description: An array of phone numbers in the user's PayPal profile.
      items:
        $ref: "#/components/schemas/phone"
    properties:
      type: object
      title: Properties
      description: Properties.
    qr_code:
      type: object
      title: QR Code
      description: The base64-encoded image of the `image/png` type.
      properties:
        image:
          type: string
          description: The base64-encoded image of the `image/png` type.
    refund-detail:
      type: object
      title: Refund Detail
      description: The invoicing refund details.
      properties:
        type:
          type: string
          description: The PayPal refund type. Indicates whether the refund was paid
            through PayPal or externally in the invoicing flow. The [record
            refund](/docs/api/invoicing/v1/#invoices_record-refund) method
            supports the `EXTERNAL` refund type. The `PAYPAL` refund type is
            supported for backward compatibility.
          enum:
            - PAYPAL
            - EXTERNAL
          readOnly: true
        transaction_id:
          type: string
          description: The ID of the PayPal refund transaction. Required for the `PAYPAL`
            refund type.
          readOnly: true
        date:
          type: string
          description: The date when the invoice was refunded, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, `2014-02-27 PST`.
          format: date-time
        note:
          type: string
          description: A note associated with the refund.
        amount:
          $ref: "#/components/schemas/currency"
          description: The currency and amount to record as refunded. If you omit the
            amount, the total invoice paid amount is recorded as refunded.
    refund-detail_list:
      type: array
      description: An array of refund details for the invoice.
      maxItems: 1
      items:
        $ref: "#/components/schemas/refund-detail"
      readOnly: true
    search:
      type: object
      title: Search
      description: The invoice search parameters.
      properties:
        email:
          type: string
          description: The initial letters of the email address.
        recipient_first_name:
          type: string
          description: The initial letters of the recipient's first name.
        recipient_last_name:
          type: string
          description: The initial letters of the recipient's last name.
        recipient_business_name:
          type: string
          description: The initial letters of the recipient's business name.
        number:
          type: string
          description: Any part of the invoice number.
        status:
          type: string
          description: 'The invoice status. To search by status, specify this value as an
            array. For example, `"status": ["REFUNDED"]`. The status indicates
            the phase of the invoice in its
            lifecycle:<table><thead><tr><th>Status</th><th>Occurs
            when</th></tr></thead><tbody><tr><td><code>CANCELLED</code></td><td><p>A
            merchant or customer <a
            href="/docs/api/invoicing/v1/#invoices_cancel">cancels a sent
            invoice</a>.</p></td></tr><tr><td><code>DRAFT</code></td><td><p>A
            merchant <a href="/docs/api/invoicing/v1/#invoices_create">creates a
            draft invoice</a>.</p><blockquote><strong>Note:</strong> A customer
            cannot pay an invoice until a merchant sends
            it.</blockquote></td></tr><tr><td><code>MARKED_AS_PAID</code></td><td><p>A
            merchant <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">marks an
            invoice as paid</a> after he or she receives a check or cash payment
            for the
            invoice.</p></td></tr><tr><td><code>MARKED_AS_REFUNDED</code></td><td><p>A
            merchant <a
            href="/docs/api/invoicing/v1/#invoices_record-refund">marks an
            invoice as refunded</a>.</p><blockquote><strong>Note:</strong> A
            merchant can only mark a <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">marked-as-paid
            invoice</a> as
            refunded.</blockquote></td></tr><tr><td><code>PAID</code></td><td><p>A
            customer fully pays an invoice. It is marked as paid through one or
            both of these methods:</p><ul><li>A merchant <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">marks an
            invoice as paid</a> after he or she receives a check or cash payment
            from the customer for the invoice.</li><li>A customer makes an
            online payment for the
            invoice.</li></ul></td></tr><tr><td><code>PARTIALLY_PAID</code></td><td><p>A
            merchant or customer fully pays an invoice through one or both of
            these methods:</p><ul><li>A merchant <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">marks an
            invoice as paid</a> after he or she receives a check or cash payment
            from the customer for the invoice.</li><li>A customer makes an
            online payment for the
            invoice.</li></ul></td></tr><tr><td><code>PARTIALLY_REFUNDED</code></td><td><p>A
            merchant partially refunds an invoice through one or both of these
            methods:</p><ul><li>A merchant <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">marks an
            invoice as refunded</a>. To complete this action, the merchant must
            previously <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">mark the
            invoice as paid</a>.</li><li>A merchant makes an online refund for
            an online invoice
            payment.</li></ul></td></tr><tr><td><code>PAYMENT_PENDING</code></td><td><p>A
            customer pays an invoice but the payment is pending for one of these
            reasons:</p><ul><li>The payment is an uncleared eCheck.</li><li>The
            payment is in an accept or deny state upon which the merchant must
            act.</li><li>PayPal risk is reviewing the
            payment.</li></ul><blockquote><strong>Note:</strong> Most payments
            never go into a payment-pending
            state.</blockquote></td></tr><tr><td><code>REFUNDED</code></td><td><p>A
            merchant fully refunds an invoice through one or both of these
            methods:</p><ul><li>A merchant <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">marks an
            invoice as refunded</a>. To complete this action, the merchant must
            previously <a
            href="/docs/api/invoicing/v1/#invoices_record-payment">mark the
            invoice as paid</a>.</li><li>A merchant makes an online refund for
            an online invoice
            payment.</li></ul></td></tr><tr><td><code>SCHEDULED</code></td><td><p>A
            merchant <a
            href="/docs/api/invoicing/v1/#invoices_schedule">schedules an
            invoice</a> to be emailed by PayPal on a specified
            date.</p></td></tr><tr><td><code>SENT</code></td><td><p>A merchant
            <a href="/docs/api/invoicing/v1/#invoices_send">sends an invoice</a>
            to the customer.</p><p>After the merchant sends the
            invoice:</p><ul><li>PayPal emails the invoice to the
            customer.</li><li>A <strong>Payment</strong> button appears on the
            invoice. The customer can now pay the invoice.</li><li>In a web app,
            the invoice appears as <code>Unpaid
            (sent)</code>.</li></ul></td></tr><tr><td><code>UNPAID</code></td><td><p>A
            merchant <a href="/docs/api/invoicing/v1/#invoices_send">sends an
            invoice</a> and sets the <code>notify_merchant</code> and
            <code>notify_customer</code> query parameters to <code>false</code>
            to suppress the PayPal email notification. Then, the merchant
            manually sends the invoice link in his or her own
            email.</p></td></tr></tbody></table>'
          enum:
            - DRAFT
            - SENT
            - SCHEDULED
            - PAID
            - MARKED_AS_PAID
            - CANCELLED
            - REFUNDED
            - PARTIALLY_REFUNDED
            - MARKED_AS_REFUNDED
        lower_total_amount:
          type: string
          description: The lower limit of the total amount.
        upper_total_amount:
          type: string
          description: The upper limit of the total amount.
        start_invoice_date:
          type: string
          format: date
          description: The start date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        end_invoice_date:
          type: string
          format: date
          description: The end date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        start_due_date:
          type: string
          format: date
          description: The start due date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        end_due_date:
          type: string
          format: date
          description: The end due date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        start_payment_date:
          type: string
          format: date
          description: The start payment date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        end_payment_date:
          type: string
          format: date
          description: The end payment date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        start_creation_date:
          type: string
          format: date
          description: The start creation date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        end_creation_date:
          type: string
          format: date
          description: The end creation date for the invoice, in [Internet date and time
            format](https://tools.ietf.org/html/rfc3339#section-5.6). For
            example, *yyyy*-*MM*-*dd* *z*.
        page:
          type: number
          description: The zero-relative start index of the entire list of merchant
            invoices to return in the response. So, a combination of `page=0`
            and `page_size=20` returns the first 20 invoices. A combination of
            `page=20` and `page_size=20` returns the next 20 invoices.
        page_size:
          type: number
          description: The page size for the search results.
        total_count_required:
          type: boolean
          description: Indicates whether the response shows the total count.
          default: false
        archived:
          type: boolean
          description: Indicates whether to list merchant-archived invoices in the
            response. If `true`, response lists only merchant-archived invoices.
            If `false`, response lists only unarchived invoices. If `null`,
            response lists all invoices.
    shipping-cost:
      type: object
      title: Shipping Cost
      description: The shipping cost, as a percent or amount value.
      properties:
        amount:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the shipping charge. Value is from `0`
            to `1000000`. Supports up to two decimal places.
        tax:
          $ref: "#/components/schemas/tax"
          description: The tax percentage on the shipping amount.
    shipping-info:
      type: object
      title: Shipping Information
      description: The shipping information for the invoice recipient.
      properties:
        first_name:
          type: string
          description: The first name of the recipient at the shipping address.
          maxLength: 256
        last_name:
          type: string
          description: The last name of the recipient at the shipping address.
          maxLength: 256
        business_name:
          type: string
          description: The business name of the recipient at the shipping address.
          maxLength: 480
        address:
          $ref: "#/components/schemas/address"
          description: The shipping address.
    tax:
      type: object
      title: Tax
      description: The tax information.
      properties:
        name:
          type: string
          description: The tax name.
          maxLength: 100
        percent:
          type: number
          description: The tax rate. Value is from `0` to `100`. Supports up to five
            decimal places.
          minimum: 0
        amount:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the calculated tax.
          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
    template:
      type: object
      title: Template
      description: The invoicing template.
      properties:
        template_id:
          type: string
          description: The ID of the template.
          readOnly: true
        name:
          type: string
          description: The template name.<blockquote><strong>Note:</strong> The template
            name must be unique.</blockquote>
        default:
          type: boolean
          description: Indicates whether this template is the default merchant template. A
            merchant can have one default template.
        template_data:
          $ref: "#/components/schemas/template-data"
        settings:
          $ref: "#/components/schemas/template-settings_list"
        unit_of_measure:
          type: string
          description: The unit of measure for the template.
          enum:
            - HOURS
            - QUANTITY
            - AMOUNT
        custom:
          type: boolean
          description: Indicates whether this template is a merchant-created custom
            template. The system generates non-custom templates.
          readOnly: true
        links:
          $ref: "#/components/schemas/link_description_list"
    template-data:
      type: object
      title: Template Data
      description: The template data.
      properties:
        merchant_info:
          $ref: "#/components/schemas/merchant-info"
        billing_info:
          $ref: "#/components/schemas/definitions-billing-info_list"
        shipping_info:
          $ref: "#/components/schemas/shipping-info"
        cc_info:
          $ref: "#/components/schemas/email_list"
        items:
          $ref: "#/components/schemas/definitions-invoice-item_list"
        payment_term:
          $ref: "#/components/schemas/payment-term"
        reference:
          type: string
          description: The reference data, such as a PO number.
          maxLength: 60
        discount:
          $ref: "#/components/schemas/discount"
          description: The invoice level discount, as a percent or an amount value.
        shipping_cost:
          $ref: "#/components/schemas/shipping-cost"
          description: The shipping cost, as a percent or an amount value.
        custom:
          $ref: "#/components/schemas/custom-amount"
        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 merchants in `India`, `Brazil`, or
            `Israel`.</blockquote>
          default: false
        minimum_amount_due:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the minimum allowed for a partial
            payment. Valid only when `allow_partial_payment` is `true`.
        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: false
        tax_inclusive:
          type: boolean
          description: Indicates whether the unit price includes tax.
          default: false
        terms:
          type: string
          description: The general terms of the invoice.
          maxLength: 4000
        note:
          type: string
          description: A note to the invoice recipient. This note also appears on the
            invoice notification email.
          maxLength: 4000
        merchant_memo:
          type: string
          description: A private bookkeeping memo for the merchant.
          maxLength: 150
        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: 4000
        total_amount:
          $ref: "#/components/schemas/currency"
          description: The currency and amount of the invoice total.
          readOnly: true
        attachments:
          $ref: "#/components/schemas/definitions-file-attachment_list"
      required:
        - merchant_info
    template-settings:
      type: object
      title: Template Settings
      description: The template settings.
      properties:
        field_name:
          type: string
          description: The field name in `template_data` for which to map corresponding
            display preferences.
          enum:
            - items.quantity
            - items.description
            - items.date
            - items.discount
            - items.tax
            - discount
            - shipping
            - custom
        display_preference:
          $ref: "#/components/schemas/template-settings-metadata"
    template-settings-metadata:
      type: object
      title: Template Settings Metadata
      description: The template settings metadata.
      properties:
        hidden:
          type: boolean
          description: Indicates whether to show or hide this field.
          default: false
    template-settings_list:
      type: array
      description: An array of template settings that describe which fields to show or
        hide when creating an invoice.
      items:
        $ref: "#/components/schemas/template-settings"
    template_list:
      type: array
      description: The details for each template. If `fields` is `none`, returns only
        the template name, ID, and default status.
      items:
        $ref: "#/components/schemas/template"
    templates:
      type: object
      title: Templates
      minItems: 1
      description: A merchant-created template with associated details. The associated
        details include the emails, addresses, and phone numbers from the user's
        PayPal profile.
      properties:
        addresses:
          $ref: "#/components/schemas/address_list"
        emails:
          $ref: "#/components/schemas/emails_list"
        phones:
          $ref: "#/components/schemas/phone_list"
        templates:
          $ref: "#/components/schemas/template_list"
        links:
          $ref: "#/components/schemas/link_description_list"
  parameters:
    page:
      name: page
      in: query
      description: The *zero-relative* start index of the entire list of merchant
        invoices that are returned in the response. So, the combination of
        `page=0` and `page_size=20` returns the first 20 invoices. The
        combination of `page=20` and `page_size=20` returns the next 20
        invoices.
      schema:
        type: integer
        default: 1
    page_size:
      name: page_size
      in: query
      description: The number of invoices to return in the response.
      schema:
        type: integer
        default: 20
    total_count_required:
      name: total_count_required
      in: query
      description: Indicates whether to show the total count in the response.
      schema:
        type: boolean
        default: false
    invoice_id:
      name: invoice_id
      in: path
      description: The ID of the invoice for which to generate a QR code.
      required: true
      schema:
        type: string
    notify_merchant:
      name: notify_merchant
      in: query
      description: Indicates whether to send the invoice update notification to the
        merchant.
      schema:
        type: boolean
        default: true
    transaction_id:
      name: transaction_id
      in: path
      description: The ID of the external refund transaction to delete.
      required: true
      schema:
        type: string
    width:
      name: width
      in: query
      description: The width, in pixels, of the QR code image. Value is from `150` to `500`.
      schema:
        type: integer
        default: 500
    height:
      name: height
      in: query
      description: The height, in pixels, of the QR code image. Value is from `150` to
        `500`.
      schema:
        type: integer
        default: 500
    fields:
      name: fields
      in: query
      description: The fields to return in the response. Value is `all` or `none`. To
        return only the template name, ID, and default attributes, specify
        `none`.
      schema:
        type: string
        default: all
    template_id:
      name: template_id
      in: path
      description: The ID of the template to update.
      required: true
      schema:
        type: string
x-errors:
  - name: AUTHORIZATION_ERROR
    message: Authorization error occurred.
    description: Check your credentials.
  - name: BUSINESS_ERROR
    message: Invoicing business error.
    description: See the message for a brief description of the error.
  - name: INTERNAL_SERVICE_ERROR
    message: An internal service error has occurred.
    description: Resend the request at another time. If this error continues,
      contact [PayPal Merchant Technical
      Support](https://developer.paypal.com/webapps/developer/support).
  - name: MALFORMED_REQUEST_ERROR
    message: JSON request malformed.
    description: Correct the JSON request body and resend the request.
  - name: RESOURCE_NOT_FOUND_ERROR
    message: Resource not found.
    description: The resource was not found.
  - name: UNKNOWN_ERROR
    message: Unknown exception occurred.
    description: If this error continues, contact [PayPal Merchant Technical
      Support](https://developer.paypal.com/webapps/developer/support).
  - name: USER_BUSINESS_ERROR
    message: User business error.
    description: See the message for a brief description of the error.
  - name: VALIDATION_ERROR
    message: Invalid request - see details.
    description: One or more validation errors have occurred. Review the details for
      specific validation errors.