openapi: 3.0.1
info:
  title: Elevate Invoices API
  description: >
    ### Invoice


    Provides read and write access to customer invoices and invoice payment
    events


    #### Definitions

    * Invoice - a record of charges for a customer. They maybe 'normal' or
    'adhoc' and are split into Invoice and Invoice Summary providing the break
    down of charges

    * InvoicePaymentEvent - a change to an invoice as a result of payments,
    refunds or state changes
  version: '1.21'
servers:
  - url: https://rest.elevatebilling.com/v1
tags:
  - name: invoices
    description: Customer invoices
  - name: invoice-payment-events
    description: >-
      Invoice state changes. Can be used to write off or dispute to and from
      unpaid  invoices
paths:
  /invoices:
    get:
      tags:
        - invoices
      summary: Get a list of invoices
      operationId: getInvoices
      x-si-permissions:
        - VIEW_SITE
      x-si-filterable: true
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: id
          in: query
          description: Filter by generated invoice identifier
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: contractOwnerId
          in: query
          description: Filter by contract owner identifier
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: billingCycleId
          in: query
          description: Filter by billing cycle identifier
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: billRunId
          in: query
          description: Filter by bill run identifier
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: billRunType
          in: query
          description: Filter by bill run type
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: billRunStatus
          in: query
          description: Filter by bill run status
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: customerId
          in: query
          description: Filter by customer identifier
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: siteId
          in: query
          description: Filter by site identifier
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: dueDate
          in: query
          description: Filter by invoice due date
          schema:
            $ref: '#/components/schemas/DateFilterParam'
          required: false
        - name: invoiceDate
          in: query
          description: Filter by invoice date
          schema:
            $ref: '#/components/schemas/DateFilterParam'
          required: false
        - name: paymentMethod
          in: query
          description: Filter by payment method
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: mandateStatus
          in: query
          description: Filter by mandate status
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: paymentStatus
          in: query
          description: Filter by invoice payment status
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: thirdPartyPaymentStatus
          in: query
          description: Filter by invoice payment status of the integrated payment provider
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: invoiceNumber
          in: query
          description: Filter by invoice number
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: createdDate
          in: query
          description: Filter by created date
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: thirdPartyPaymentStatusUpdatedTime
          in: query
          description: Filter by third party payment status updated date and time
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: paymentStatusUpdatedDate
          in: query
          description: Filter by payment status updated date
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: refundStatusUpdatedDate
          in: query
          description: Filter by refund status updated date
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: thirdPartyRefundStatus
          in: query
          description: Filter by third party refund status
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: paymentStatusUpdatedTime
          in: query
          description: Filter by payment status updated date and time
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Invoice'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /invoices/{billRunType}/{invoice_id}:
    get:
      tags:
        - invoices
      summary: Get the invoice in PDF format
      operationId: getInvoicePDF
      x-si-permissions:
        - VIEW_SITE
      x-si-filterable: false
      security:
        - bearerAuth: []
      parameters:
        - name: invoice_id
          in: path
          description: Invoice identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
        - name: billRunType
          in: path
          description: Bill Run Type
          required: true
          schema:
            $ref: '#/components/schemas/BillRunType'
      responses:
        '200':
          description: A PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
  /invoice-summaries/{billRunType}/{invoice_summary_id}:
    get:
      tags:
        - invoices
      summary: Get the invoice summary in PDF format
      operationId: getInvoiceSummaryPDF
      x-si-permissions:
        - VIEW_SITE
      x-si-filterable: false
      security:
        - bearerAuth: []
      parameters:
        - name: invoice_summary_id
          in: path
          description: Invoice summary identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
        - name: billRunType
          in: path
          description: Bill Run Type
          required: true
          schema:
            $ref: '#/components/schemas/BillRunType'
      responses:
        '200':
          description: A PDF file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            text/plain: {}
        '401':
          description: Unauthorized
          content:
            application/json: {}
        '403':
          description: Forbidden
          content:
            application/json: {}
        '404':
          description: Not Found
          content:
            application/json: {}
  /invoice-payment-events:
    get:
      tags:
        - invoice-payment-events
      summary: Get a list of invoice payment events
      operationId: getInvoicePaymentEvents
      x-si-permissions:
        - VIEW_REPORTING_INVOICES
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - name: customerId
          in: query
          description: Customer identifier
          required: false
          schema:
            $ref: '#/components/schemas/IdParam'
        - name: invoiceId
          in: query
          description: Invoice identifier
          required: false
          schema:
            $ref: '#/components/schemas/IdParam'
        - name: billRunType
          in: query
          description: Bill Run Type
          required: false
          schema:
            $ref: '#/components/schemas/BillRunType'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoicePaymentEvent'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
    post:
      tags:
        - invoice-payment-events
      summary: Create a new invoice payment event
      description: >-
        Create a new invoice payment event. Used for disputing an invoice,
        writing off an invoice, undisputing, un-writting off and undoing a
        payment for an invoice made in error
      operationId: createInvoicePaymentEvent
      x-si-permissions:
        - UPDATE_REPORTING_INVOICES
      security:
        - bearerAuth: []
      requestBody:
        description: New invoice payment event
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoicePaymentEvent'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePaymentEvent'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoicePaymentEvent'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content:
            application/json: {}
  /resend-invoice:
    post:
      tags:
        - invoices
      summary: Resend customer invoice email
      description: Resend customer invoice email to configured contacts
      operationId: resendInvoice
      x-si-permissions:
        - RESEND_CUSTOMER_INVOICE
      security:
        - bearerAuth: []
      requestBody:
        description: Resend customer invoice email request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendEmailRequest'
        required: true
      responses:
        '200':
          description: OK
          content: {}
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
components:
  schemas:
    InvoicePaymentEvent:
      required:
        - invoiceId
        - billRunType
        - paymentStatus
        - notes
      type: object
      properties:
        id:
          description: Invoice History identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        invoiceId:
          description: Invoice identifier
          type: integer
          format: int64
          example: 0
        customerId:
          type: integer
          description: Customer identifier
          format: int64
          readOnly: true
          example: 1
        billRunType:
          $ref: '#/components/schemas/BillRunType'
        paymentStatus:
          $ref: '#/components/schemas/PaymentStatus'
        notes:
          description: Notes on payment change
          type: string
          minLength: 0
          maxLength: 255
          pattern: '[\w\p{L}\s%£@&#='':;`’,|!_—–\(\)\\/\-\+\.\?\*\$]*'
        amountInMajorCurrency:
          description: Amount in major currency (e.g pounds/dollars/euros)
          type: number
          example: 10.5
          minimum: 0.01
          maximum: 100000
    Invoice:
      type: object
      readOnly: true
      properties:
        id:
          description: Invoice identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        invoiceSummaryId:
          description: Invoice summary identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        contractOwnerId:
          description: Contract owner identifier
          type: integer
          format: int32
          example: 0
        billingCycleId:
          description: Billing cycle identifier
          type: integer
          format: int64
          example: 0
        billRunId:
          description: Bill run identifier
          type: integer
          format: int64
          example: 0
        billRunType:
          $ref: '#/components/schemas/BillRunType'
        billRunStatus:
          $ref: '#/components/schemas/BillRunStatus'
        customerId:
          description: Customer identifier
          type: integer
          format: int64
          example: 0
        siteId:
          description: Site identifier
          type: integer
          format: int64
          example: 0
        dueDate:
          description: Invoice due date
          type: string
          format: date
        invoiceDate:
          description: Invoice date
          type: string
          format: date
        createdDate:
          description: Invoice created date
          type: string
          format: date
        thirdPartyPaymentStatusUpdatedTime:
          description: Invoice thirdPartyPaymentStatus updated date and time
          type: string
          format: date-time
        paymentStatusUpdatedDate:
          description: >-
            Invoice paymentStatus updated date (deprecated and can be removed in
            future releases, use paymentStatusUpdatedTime instead)
          type: string
          format: date
        paymentStatusUpdatedTime:
          description: Invoice paymentStatus updated date and time
          type: string
          format: date-time
        refundStatusUpdatedDate:
          description: Invoice thirdPartyRefundStatus updated date
          type: string
          format: date
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        mandateStatus:
          $ref: '#/components/schemas/PaymentProviderMandateStatus'
        paymentStatus:
          $ref: '#/components/schemas/PaymentStatus'
        thirdPartyPaymentStatus:
          $ref: '#/components/schemas/ThirdPartyPaymentStatus'
        thirdPartyRefundStatus:
          $ref: '#/components/schemas/ThirdPartyRefundStatus'
        invoiceNumber:
          description: Invoice Number
          type: string
        invoiceTotalAmount:
          description: Invoice total amount
          type: number
          format: decimal
        invoiceTaxAmount:
          description: Invoice total tax amount
          type: number
          format: decimal
        taxExempt:
          type: boolean
          description: Invoice is tax exempt
        purchaseOrderNumber:
          description: Purchase Order Number
          type: string
        invoiceRemainingAmount:
          description: Invoice remaining amount
          type: number
          format: decimal
        totalRentalAmount:
          type: number
          description: Invoice total rental charge amount
          format: decimal
          readOnly: true
        totalRentalTaxAmount:
          type: number
          description: Invoice total rental charge tax amount
          format: decimal
          readOnly: true
        totalUsageAmount:
          type: number
          description: Invoice total usage charge amount
          format: decimal
          readOnly: true
        totalUsageTaxAmount:
          type: number
          description: Invoice total usage charge tax amount
          format: decimal
          readOnly: true
        usageBreakdown:
          type: array
          items:
            $ref: '#/components/schemas/UsageBreakdown'
        totalAdhocAmount:
          type: number
          description: Invoice total adhoc charge amount
          format: decimal
          readOnly: true
        totalAdhocTaxAmount:
          type: number
          description: Invoice total adhoc charge tax amount
          format: decimal
          readOnly: true
        totalBoltOnAmount:
          type: number
          description: Invoice total bolt-on charge amount
          format: decimal
          readOnly: true
        totalBoltOnTaxAmount:
          type: number
          description: Invoice total bolt-on charge tax amount
          format: decimal
          readOnly: true
        totalReverseVatAmount:
          type: number
          description: Invoice total reverse-vat charge amount
          format: decimal
          readOnly: true
        paymentRetryCount:
          description: Number of payment retries attempted
          type: integer
          format: int32
          example: 0
          readOnly: true
    UsageBreakdown:
      type: object
      properties:
        usageProductId:
          type: integer
          description: Usage Product identifier
          format: int32
          example: 0
        chargeGroupCategoryId:
          type: integer
          description: Charge group category identifier
          format: int32
          example: 0
        taxBandId:
          type: integer
          description: Tax Band identifier
          format: int32
          example: 0
        costPrice:
          type: number
          description: Net unrated cost price
          format: decimal
        sellPrice:
          type: number
          description: Net rated sell price
          format: decimal
        taxAmount:
          type: number
          description: Tax amount
          format: decimal
        ratedCostPrice:
          type: number
          description: Net rated cost price
          format: decimal
    ResendEmailRequest:
      required:
        - invoiceId
        - billRunType
      type: object
      properties:
        invoiceId:
          description: Invoice identifier
          type: integer
          format: int64
          example: 0
        billRunType:
          $ref: '#/components/schemas/BillRunType'
    BillRunType:
      description: Billing run type
      type: string
      enum:
        - NORMAL
        - ADHOC
    PaymentStatus:
      description: Invoice payment status
      type: string
      enum:
        - NA
        - PAID
        - UNPAID
        - PENDING
        - REFUNDED
        - PART_REFUNDED
        - REFUND_PENDING
        - WRITTEN_OFF
        - DISPUTED
        - PARTIALLY_PAID
    PageParam:
      description: Page of results to show
      minimum: 1
      type: integer
      format: int32
      example: 1
    ResultsPerPageParam:
      description: Results to return per page
      maximum: 1000
      minimum: 1
      type: integer
      format: int32
      example: 100
    SortParam:
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      example: id,name | name:desc
      type: string
    FieldsParam:
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      example: id,name
      type: string
    IdFilterParam:
      description: Filter by this numeric id value
      example: '0'
      type: string
    StringFilterParam:
      description: >-
        Filter by this string value where value can optionally be prefixed
        (in:|like:)
      example: xyz | in:x,y | like:xyz
      type: string
    DateFilterParam:
      description: >-
        Filter by this date value where value can optionally be prefixed
        (gt:|lt:|gtn:|gen:)
      example: yyyy-MM-dd | lt:yyyy-MM-dd | gt:yyyy-MM-dd | gtn:yyyy-MM-dd
      type: string
    BillRunStatus:
      description: Bill run status
      type: string
      enum:
        - OPEN
        - CLOSED
        - FINALIZED
    PaymentMethod:
      description: Payment method
      type: string
      enum:
        - CHEQUE
        - DIRECT_DEBIT
        - CANCELLED_DD
        - CANCELLED_CARD
        - CREDIT_CARD
        - PAYPAL
        - BACS
        - POST_OFFICE_PAYMENT_CARD
        - EZYPAY
        - GO_CARDLESS
        - GC_INSTANT_BANK_PAYMENTS
        - STRIPE
        - STRIPE_CARD
        - STRIPE_DD
        - FINASTRA
        - FAST_PAY
        - OTHER
    PaymentProviderMandateStatus:
      description: Invoice payment status
      type: string
      enum:
        - NEW
        - INACTIVE
        - CREATED
        - CUSTOMER_APPROVAL_GRANTED
        - CUSTOMER_APPROVAL_SKIPPED
        - ACTIVE
        - CANCELLED
        - FAILED
        - TRANSFERRED
        - EXPIRED
        - SUBMITTED
        - RESUBMISSION_REQUESTED
        - PENDING_SUBMISSION
        - REINSTATED
        - REPLACED
        - PENDING_CUSTOMER_APPROVAL
        - CONSUMED
        - BLOCKED
        - UNKNOWN
    ThirdPartyPaymentStatus:
      description: Invoice payment status. Not applicable for manual payments
      type: string
      enum:
        - NEW
        - CREATED
        - PENDING_CUSTOMER_APPROVAL
        - PENDING_SUBMISSION
        - SUBMITTED
        - CONFIRMED
        - PAID_OUT
        - CANCELLED
        - FAILED
        - FAILED_RETRYING
        - CHARGED_BACK
        - CUSTOMER_APPROVAL_GRANTED
        - CUSTOMER_APPROVAL_DENIED
        - CHARGEBACK_CANCELLED
        - LATE_FAILURE_SETTLED
        - CHARGEBACK_SETTLED
        - SURCHARGE_FEE_DEBITED
        - RESUBMISSION_REQUESTED
        - UNSUPPORTED_PAYMENT_TYPE
        - UNAUTHORISED_PAYMENT_TYPE
        - CUSTOMER_APPROVAL_MISSING
        - SURCHARGE_FEE_CREDITED
        - MANUALLY_PAID
        - UNSENT
        - REFUNDED
        - PARTIALLY_REFUNDED
        - REFUND_PENDING
    ThirdPartyRefundStatus:
      description: Third party refund status
      type: string
      readOnly: true
      enum:
        - CREATED
        - PENDING_SUBMISSION
        - SUBMITTED
        - PAID
        - CANCELLED
        - BOUNCED
        - FUNDS_RETURNED
        - MANUALLY_REFUNDED
        - REFUND_SETTLED
    IdParam:
      description: Identifier
      minimum: 1
      type: integer
      format: int64
      example: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    page:
      name: page
      in: query
      description: Page of results to show
      schema:
        $ref: '#/components/schemas/PageParam'
      required: true
    pageSize:
      name: pageSize
      description: Results to return per page
      in: query
      schema:
        $ref: '#/components/schemas/ResultsPerPageParam'
      required: true
    sort:
      name: sort
      in: query
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      schema:
        $ref: '#/components/schemas/SortParam'
      required: false
    fields:
      name: fields
      in: query
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      schema:
        $ref: '#/components/schemas/FieldsParam'
      required: false
