openapi: 3.0.1
info:
  title: Elevate Bill Run API
  description: >
    ### bill runs 


    Provides read & write access to bill run entities.


    #### Definitions

    * Bill run - a process by which customers are invoiced for their usage,
    rental and adhoc charges
  version: '1.9'
servers:
  - url: https://rest.elevatebilling.com/v1
tags:
  - name: bill-runs
    description: >-
      a process by which customers are invoiced for their usage, rental and
      adhoc charges
paths:
  /bill-runs:
    get:
      tags:
        - bill-runs
      summary: Get a list of available bill runs
      operationId: getBillRuns
      x-si-permissions:
        - VIEW_BILLING_RUN
      x-si-filterable: true
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: billRunStatus
          in: query
          description: Filter by bill run status
          schema:
            $ref: '#/components/schemas/BillRunStatus'
          required: false
        - name: billingCycleId
          in: query
          description: Filter by billing cycle id
          schema:
            $ref: '#/components/schemas/IdParam'
          required: false
        - name: billingCycleGroupName
          in: query
          description: Filter by billing cycle group name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillRun'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /bill-runs/{bill_run_id}:
    get:
      tags:
        - bill-runs
      summary: Get a specific bill run
      operationId: getBillRun
      x-si-permissions:
        - VIEW_BILLING_RUN
      security:
        - bearerAuth: []
      parameters:
        - name: bill_run_id
          in: path
          description: Bill run identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      responses:
        '200':
          description: Bill run found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRun'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
    patch:
      tags:
        - bill-runs
      summary: Update a specific bill run
      description: >-
        Close, reopen, and move a bill run to the next step. To fully close the
        bill run please initially patch the billRunStatus to CLOSED and
        summaryStatus to REPORTING. To generate draft invoices of a CLOSED bill
        run, PATCH the summaryStatus to DRAFT_INVOICES. To generate full
        invoices of a CLOSED bill run, PATCH the summaryStatus to FULL_INVOICES.
        To distribute and finalise the bill run having generated invoices, PATCH
        the summaryStatus to DISTRIBUTION. Please refer to the examples
      operationId: updateBillRun
      x-si-json-patch: true
      x-si-allow-patch:
        - /billRunStatus
        - /summaryStatus
        - /invoiceDate
        - /paused
      x-si-permissions:
        - UPDATE_BILLING_RUN
      security:
        - bearerAuth: []
      parameters:
        - name: bill_run_id
          in: path
          description: Bill run identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      requestBody:
        description: A set of JSONPatch operations to be performed
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              CloseAndGenerateReports:
                value:
                  - op: replace
                    path: /billRunStatus
                    value: CLOSED
                  - op: replace
                    path: /summaryStatus
                    value: REPORTING
                  - op: replace
                    path: /invoiceDate
                    value: '2023-02-04'
              ProduceDraftInvoices:
                value:
                  op: replace
                  path: /summaryStatus
                  value: DRAFT_INVOICES
              ProduceFullInvoices:
                value:
                  op: replace
                  path: /summaryStatus
                  value: FULL_INVOICES
              DistributeAndFinalise:
                value:
                  op: replace
                  path: /summaryStatus
                  value: DISTRIBUTION
              Reopen:
                value:
                  - op: replace
                    path: /billRunStatus
                    value: OPEN
                  - op: replace
                    path: /summaryStatus
                    value: PROPERTIES
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRun'
        '400':
          description: Invalid Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
  /adjust-bill-run-schedule/{bill_run_id}:
    post:
      tags:
        - bill-runs
      summary: Adjust the schedule of the bill run by specified number of periods
      operationId: adjustBillRunSchedule
      x-si-permissions:
        - UPDATE_BILLING_RUN
      security:
        - bearerAuth: []
      parameters:
        - name: bill_run_id
          in: path
          description: Bill run identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
        - name: periods
          in: query
          description: Number of periods to adjust the start date of the bill run
          schema:
            type: integer
            format: int32
          example: 1
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillRun'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /adhoc-bill-runs:
    get:
      tags:
        - adhoc-bill-runs
      summary: Get a list of available adhoc bill runs
      operationId: getAdhocBillRuns
      x-si-permissions:
        - VIEW_BILLING_RUN
      x-si-filterable: true
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: billRunStatus
          in: query
          description: Filter by adhoc bill run status
          schema:
            $ref: '#/components/schemas/BillRunStatus'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AdhocBillRun'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /adhoc-bill-runs/{adhoc_bill_run_id}:
    get:
      tags:
        - adhoc-bill-runs
      summary: Get a specific adhoc bill run
      operationId: getAdhocBillRun
      x-si-permissions:
        - VIEW_BILLING_RUN
      security:
        - bearerAuth: []
      parameters:
        - name: adhoc_bill_run_id
          in: path
          description: Adhoc bill run identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      responses:
        '200':
          description: Adhoc bill run found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdhocBillRun'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
    patch:
      tags:
        - adhoc-bill-runs
      summary: Update a specific adhoc bill run
      description: >-
        Close, reopen, and move an adhoc bill run to the next step. To fully
        close the adhoc bill run please initially patch the summaryStatus to
        REPORTING. To generate invoices of a CLOSED adhoc bill run, PATCH the
        summaryStatus to FULL_INVOICES. To distribute and finalise the adhoc
        bill run having generated invoices, PATCH the summaryStatus to
        DISTRIBUTION. You can monitor the progress of the bill run summary state
        by doing a GET and looking at the summaryStatusPercentage. Please refer
        to the examples
      operationId: updateAdhocBillRun
      x-si-json-patch: true
      x-si-allow-patch:
        - /billRunStatus
        - /summaryStatus
        - /invoiceDate
        - /nickname
      x-si-permissions:
        - UPDATE_BILLING_RUN
      security:
        - bearerAuth: []
      parameters:
        - name: adhoc_bill_run_id
          in: path
          description: Adhoc bill run identifier
          required: true
          schema:
            $ref: '#/components/schemas/IdParam'
      requestBody:
        description: A set of JSONPatch operations to be performed
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
            examples:
              CloseAndGenerateReportsSpecifyingInvoiceDate:
                value:
                  - op: replace
                    path: /summaryStatus
                    value: REPORTING
                  - op: replace
                    path: /invoiceDate
                    value: '2023-02-04'
                  - op: replace
                    path: /nickname
                    value: Maintenance Charge
              CloseAndGenerateReports:
                value:
                  - op: replace
                    path: /summaryStatus
                    value: REPORTING
                  - op: replace
                    path: /nickname
                    value: Maintenance Charge
              ProduceInvoices:
                value:
                  op: replace
                  path: /summaryStatus
                  value: FULL_INVOICES
              DistributeAndFinalise:
                value:
                  op: replace
                  path: /summaryStatus
                  value: DISTRIBUTION
              Reopen:
                value:
                  - op: replace
                    path: /billRunStatus
                    value: OPEN
                  - op: replace
                    path: /summaryStatus
                    value: PROPERTIES
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdhocBillRun'
        '400':
          description: Invalid Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
components:
  schemas:
    BillRun:
      type: object
      required:
        - name
        - billingCycleId
        - periodStartDate
        - periodEndDate
        - invoiceDate
        - parallel
        - revenueInMajorCurrency
        - usageSuspenseCount
        - rentalSuspenseCount
      properties:
        id:
          description: Bill run identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        name:
          type: string
          readOnly: true
          description: Bill run name
          minLength: 1
          maxLength: 22
          pattern: '[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*'
        sortableName:
          type: string
          readOnly: true
          description: Sortable bill run name
          minLength: 1
          maxLength: 22
          pattern: '[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*'
        billingCycleId:
          description: Billing cycle Id
          type: integer
          format: int64
          x-si-validation: '@ValidId'
          example: 1
        created:
          description: Creation date
          readOnly: true
          type: string
          format: date
        periodStartDate:
          description: Bill run start date
          type: string
          format: date
        periodEndDate:
          description: Bill run end date
          type: string
          format: date
        invoiceDate:
          description: >-
            The billing agent may wish a date that is different to appear on the
            invoice to manage customer perception.
          type: string
          format: date
        includeUsageUntilDate:
          description: >-
            All the usage charges up to this date will be included as part of
            the bill run
          type: string
          readOnly: true
          format: date
        billRunStatus:
          $ref: '#/components/schemas/BillRunStatus'
        summaryStatus:
          $ref: '#/components/schemas/BillRunSummaryStatus'
        billingUserAdminId:
          description: Bill user who closed bill run
          type: integer
          format: int64
          readOnly: true
          x-si-validation: '@ValidId'
          example: 1
        parallel:
          description: Parallel bill run
          type: boolean
        revenueInMajorCurrency:
          description: Revenue in this bill run now
          type: integer
          format: int64
          example: 1
        usageSuspenseCount:
          description: Count of usage suspense records for this bill run now
          type: integer
          format: int64
          example: 1
        rentalSuspenseCount:
          description: Count of rental suspense records for this bill run now
          type: integer
          format: int64
          example: 1
        maxInvoiceValue:
          description: Highest value invoice in the bill run
          type: number
          format: decimal
        maxInvoiceCustomerId:
          description: Customer Id
          type: integer
          format: int64
          x-si-validation: '@ValidId'
          example: 1
        paused:
          description: >-
            Bill runs associated to cycles that are set to auto-close may be
            paused. A paused bill run will not be automatically closed/finalised
            by the system
          type: boolean
    AdhocBillRun:
      type: object
      required:
        - name
        - invoiceDate
        - revenueInMajorCurrency
      properties:
        id:
          description: Adhoc bill run identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        name:
          type: string
          description: Adhoc bill run name
          minLength: 1
          maxLength: 22
          pattern: '[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*'
        nickname:
          type: string
          description: Adhoc bill run nickname
          minLength: 1
          maxLength: 100
          pattern: '[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*'
        created:
          description: Creation date
          readOnly: true
          type: string
          format: date
        invoiceDate:
          description: Date to be shown on the invoices
          type: string
          format: date
        billRunStatus:
          $ref: '#/components/schemas/BillRunStatus'
        summaryStatus:
          $ref: '#/components/schemas/BillRunSummaryStatus'
        summaryStatusPercentage:
          description: Summary status completion percentage
          type: integer
          format: int64
          example: 100
        billingUserAdminId:
          description: Bill user who closed the adhoc bill run
          type: integer
          format: int64
          readOnly: true
          x-si-validation: '@ValidId'
          example: 1
        revenueInMajorCurrency:
          description: Revenue in this bill run now
          type: integer
          format: int64
          example: 1
        adhocProductInventoryIds:
          description: Adhoc product inventory identifiers associated to the adhoc bill run
          readOnly: true
          type: array
          items:
            type: integer
            format: int32
            x-si-validation: '@ValidId'
            example: 1
        rentalProductInventoryIds:
          description: >-
            Rental product inventory identifiers associated to the adhoc bill
            run
          readOnly: true
          type: array
          items:
            type: integer
            format: int32
            x-si-validation: '@ValidId'
            example: 1
    BillRunStatus:
      description: Bill run status
      type: string
      enum:
        - OPEN
        - CLOSED
        - FINALIZED
    BillRunSummaryStatus:
      description: Bill run summary status
      type: string
      enum:
        - PROPERTIES
        - STARTING
        - REPORTING
        - DRAFT_INVOICES
        - FULL_INVOICES
        - DISTRIBUTION
        - COMBINING_INVOICES
        - PAYMENT
        - REACTIVATING_RPIS
        - ARCHIVING
        - FINISHED
    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
    IdParam:
      description: Identifier
      minimum: 1
      type: integer
      format: int64
      example: 1
    StringFilterParam:
      description: >-
        Filter by this string value where value can optionally be prefixed
        (in:|like:)
      example: xyz | in:x,y | like:xyz
      type: string
    PatchDocument:
      description: A JSONPatch document as defined by RFC 6902
      required:
        - op
        - path
      type: object
      properties:
        op:
          type: string
          description: The JSON Patch operation to be performed
          x-si-exclude: true
          enum:
            - add
            - remove
            - replace
            - move
            - copy
            - test
        path:
          type: string
          description: A JSON-Pointer
        value:
          type: object
          properties: {}
          description: The value to be used within the operations
        from:
          type: string
          description: A string containing a JSON Pointer value
    PatchRequest:
      type: array
      description: >-
        JSON Patch is a format for describing changes to a JSON document as
        specified in RFC 6902. Refer to [jsonpatch.com](http://jsonpatch.com/)
        for more information
      items:
        $ref: '#/components/schemas/PatchDocument'
  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
