/api/v1/invoices:
    get:
      tags:
        - invoices
      summary: "List invoices"
      description: |
        Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.  
        
      operationId: getInvoices
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/status"
        - $ref: "#/components/parameters/client_id"
        - $ref: "#/components/parameters/created_at"
        - $ref: "#/components/parameters/updated_at"
        - $ref: "#/components/parameters/is_deleted"
        - $ref: "#/components/parameters/filter_deleted_clients"
        - $ref: "#/components/parameters/vendor_id"
        - name: client_status
          in: query
          description: |
            A comma separated list of invoice status strings. Valid options include:  
            - all
            - paid  
            - unpaid  
            - overdue   
          required: false
          schema:
            type: string
          example: ?client_status=paid,unpaid
        - name: number
          in: query
          description: |
            Search invoices by invoice number 
          required: false
          schema:
            type: string
          example: ?number=INV-001
        - name: filter
          in: query
          description: |
            Searches across a range of columns including:  
            - number  
            - po_number  
            - date  
            - amount  
            - balance  
            - custom_value1  
            - custom_value2  
            - custom_value3  
            - custom_value4
          required: false
          schema:
            type: string
          example: ?filter=bob
        - name: without_deleted_clients
          in: query
          description: |
            Returns the invoice list without the invoices of deleted clients.
          required: false
          schema:
            type: string
          example: ?without_deleted_clients=
        - name: overdue
          in: query
          description: |
            Returns the list of invoices that are overdue
          required: false
          schema:
            type: string
          example: ?over_due=
        - name: payable
          in: query
          description: |
            Returns the invoice list that are payable for a defined client. Please note, you must pass the client_id as the value for this query parameter
          required: false
          schema:
            type: string
          example: ?payable={client_id}
        - name: sort
          in: query
          description: Returns the list sorted by column in ascending or descending order.
          required: false
          schema:
            type: string
          example: id|desc number|desc balance|asc 
        - name: private_notes
          in: query
          description: |
            Searches on the private_notes field of the invoices
          required: false
          schema:
            type: string
          example: ?private_notes=super secret
      responses:
        200:
          description: "A list of invoices"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"
    post:
      tags:
        - invoices
      summary: "Create invoice"
      description: "Adds a invoice to a company"
      operationId: storeInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FillableInvoice"
      responses:
        200:
          description: "Returns the saved invoice entity"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"

  "/api/v1/invoices/{id}":
    get:
      tags:
        - invoices
      summary: "Show invoice"
      description: "Displays an invoice by id"
      operationId: showInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Invoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the invoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"

    put:
      tags:
        - invoices
      summary: "Update invoice"
      description: "Handles the updating of an invoice by id"
      operationId: updateInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Invoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the invoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"  
    delete:
      tags:
        - invoices
      summary: "Delete invoice"
      description: "Handles the deletion of an invoice by id"
      operationId: deleteInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Invoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns a HTTP status"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"
  "/api/v1/invoices/{id}/edit":
    get:
      tags:
        - invoices
      summary: "Edit invoice"
      description: "Displays an invoice by id for editting"
      operationId: editInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Invoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the invoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"

  /api/v1/invoices/create:
    get:
      tags:
        - invoices
      summary: "Blank invoice"
      description: "Returns a blank object with default values"
      operationId: getInvoicesCreate
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
      responses:
        200:
          description: "A blank invoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"

  /api/v1/invoices/bulk:
    post:
      tags:
        - invoices
      summary: "Bulk invoice actions"
      description: |
        There are multiple actions that are available including:  
          - bulk_download  
            summary: Bulk download an array of invoice PDFs (These are sent to the admin via email.)  
          - download  
            summary: Download a single PDF. (Returns a single PDF object)  
          - bulk_print  
            summary: Merges an array of Invoice PDFs for easy one click printing.  
          - auto_bill  
            summary: Attempts to automatically bill the invoices with the payment method on file.  
          - clone_to_invoice  
            summary: Returns a clone of the invoice.  
          - clone_to_quote  
            summary: Returns a quote cloned using the properties of the given invoice.  
          - mark_paid  
            summary: Marks an array of invoices as paid.  
          - mark_sent  
            summary: Marks an array of invoices as sent.  
          - restore  
            summary: Restores an array of invoices  
          - delete  
            summary: Deletes an array of invoices  
          - archive  
            summary: Archives an array of invoices  
          - cancel  
            summary: Cancels an array of invoices  
          - email  
            summary: Emails an array of invoices  
          - send_email  
            summary: Emails an array of invoices. Requires additional properties to be sent. `email_type`  

      operationId: bulkInvoices
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/index"
      requestBody:
        description: "Bulk action details"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: "The action to be performed ie 'bulk_download'"
                  required: true
                ids:
                  required: true
                  type: array
                  items:
                    description: "Array of hashed IDs to be bulk 'actioned - [{invoice_id_1},{invoice_id_2},{invoice_id_3},{invoice_id_4}]"
                    type: string
      responses:
        200:
          description: "The Bulk Action response"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"

  "/api/v1/invoices/{id}/{action}":
    get:
      deprecated: true
      tags:
        - invoices
      summary: "Custom invoice action"
      description: |
        Performs a custom action on an invoice.  
        The current range of actions are as follows  
        - clone_to_invoice  
        - clone_to_quote  
        - history  
        - delivery_note  
        - mark_paid  
        - download  
        - archive  
        - delete  
        - email  
      operationId: actionInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Invoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
        - name: action
          in: path
          description: "The action string to be performed"
          required: true
          schema:
            type: string
            format: string
          example: clone_to_quote
      responses:
        200:
          description: "Returns the invoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"
  "/api/v1/invoice/{invitation_key}/download":
    get:
      tags:
        - invoices
      summary: "Download invoice PDF"
      description: "Downloads a specific invoice"
      operationId: downloadInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: invitation_key
          in: path
          description: "The Invoice Invitation Key"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the invoice pdf"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"
  "/api/v1/invoices/{id}/delivery_note":
    get:
      tags:
        - invoices
      summary: "Download delivery note"
      description: "Downloads a specific invoice delivery notes"
      operationId: deliveryNote
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Invoice Hahsed Id"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the invoice delivery note pdf"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"
  "/api/v1/invoices/{id}/upload":
    put:
      tags:
        - invoices
      summary: "Add invoice document"
      description: "Handles the uploading of a document to a invoice"
      operationId: uploadInvoice
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Invoice Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the Invoice object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        401:
          $ref: "#/components/responses/401"
        403:
          $ref: "#/components/responses/403"
        422:
          $ref: "#/components/responses/422"
        default:
          $ref: "#/components/responses/default"