Skip to content

Elevate Bill Run API (1.11)

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
Download OpenAPI description
billing-rest-bill-run.json
billing-rest-bill-run.yaml
Languages
Servers
https://rest.elevatebilling.com/v1

bill-runs

a process by which customers are invoiced for their usage, rental and adhoc charges

Operations

Get a list of available bill runs

Request

Security
bearerAuth
Query
pageinteger(int32)(PageParam)>= 1required

Page of results to show

Example: page=1
pageSizeinteger(int32)(ResultsPerPageParam)[ 1 .. 1000 ]required

Results to return per page

Example: pageSize=100
sortstring(SortParam)

Comma-delimited list of the fields to sort by - defaults to ascending order, suffix :desc to change

Example: sort=id,name | name:desc
fieldsstring(FieldsParam)

Comma-delimited list of the field(s) to return if only a subset is required

Example: fields=id,name
billRunStatusstring(BillRunStatus)

Filter by bill run status

Enum"OPEN""CLOSED""FINALIZED"
billingCycleIdinteger(int64)(IdParam)>= 1

Filter by billing cycle id

Example: billingCycleId=1
billingCycleGroupNamestring(StringFilterParam)

Filter by billing cycle group name

Example: billingCycleGroupName=xyz | in:x,y | like:xyz
curl -i -X GET \
  'https://rest.elevatebilling.com/v1/bill-runs?page=1&pageSize=100&sort=id%2Cname+%7C+name%3Adesc&fields=id%2Cname&billRunStatus=OPEN&billingCycleId=1&billingCycleGroupName=xyz+%7C+in%3Ax%2Cy+%7C+like%3Axyz' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/jsonArray [
idinteger(int64)read-only

Bill run identifier

Example: 1
namestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-onlyrequired

Bill run name

sortableNamestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-only

Sortable bill run name

billingCycleIdinteger(int64)required

Billing cycle Id

Example: 1
createdstring(date)read-only

Creation date

periodStartDatestring(date)required

Bill run start date

periodEndDatestring(date)required

Bill run end date

invoiceDatestring(date)required

The billing agent may wish a date that is different to appear on the invoice to manage customer perception.

includeUsageUntilDatestring(date)read-only

All the usage charges up to this date will be included as part of the bill run

billRunStatusstring(BillRunStatus)

Bill run status

Enum"OPEN""CLOSED""FINALIZED"
summaryStatusstring(BillRunSummaryStatus)

Bill run summary status

Enum"PROPERTIES""STARTING""REPORTING""DRAFT_INVOICES""FULL_INVOICES""DISTRIBUTION""DIRECT_DEBITS""ACCOUNTING_PACKAGES""COMBINING_INVOICES""CUSTOM_REPORTS"
billingUserAdminIdinteger(int64)read-only

Bill user who closed bill run

Example: 1
parallelbooleanrequired

Parallel bill run

revenueInMajorCurrencyinteger(int64)required

Revenue in this bill run now

Example: 1
usageSuspenseCountinteger(int64)required

Count of usage suspense records for this bill run now

Example: 1
rentalSuspenseCountinteger(int64)required

Count of rental suspense records for this bill run now

Example: 1
maxInvoiceValuenumber(decimal)

Highest value invoice in the bill run

maxInvoiceCustomerIdinteger(int64)

Customer Id

Example: 1
pausedboolean

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

replayablebooleanread-only

Flag to indicate if the bill run stage can be replayed or not. If true then the PATCH endpoint can be used to move the bill run to replay distribution summary states

]
Response
application/json
[
  {
    "id": 1,
    "name": "string",
    "sortableName": "string",
    "billingCycleId": 1,
    "created": "2019-08-24",
    "periodStartDate": "2019-08-24",
    "periodEndDate": "2019-08-24",
    "invoiceDate": "2019-08-24",
    "includeUsageUntilDate": "2019-08-24",
    "billRunStatus": "OPEN",
    "summaryStatus": "PROPERTIES",
    "billingUserAdminId": 1,
    "parallel": true,
    "revenueInMajorCurrency": 1,
    "usageSuspenseCount": 1,
    "rentalSuspenseCount": 1,
    "maxInvoiceValue": 0,
    "maxInvoiceCustomerId": 1,
    "paused": true,
    "replayable": true
  }
]

Get a specific bill run

Request

Security
bearerAuth
Path
bill_run_idinteger(int64)(IdParam)>= 1required

Bill run identifier

Example: 1
curl -i -X GET \
  https://rest.elevatebilling.com/v1/bill-runs/1 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Bill run found

Bodyapplication/json
idinteger(int64)read-only

Bill run identifier

Example: 1
namestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-onlyrequired

Bill run name

sortableNamestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-only

Sortable bill run name

billingCycleIdinteger(int64)required

Billing cycle Id

Example: 1
createdstring(date)read-only

Creation date

periodStartDatestring(date)required

Bill run start date

periodEndDatestring(date)required

Bill run end date

invoiceDatestring(date)required

The billing agent may wish a date that is different to appear on the invoice to manage customer perception.

includeUsageUntilDatestring(date)read-only

All the usage charges up to this date will be included as part of the bill run

billRunStatusstring(BillRunStatus)

Bill run status

Enum"OPEN""CLOSED""FINALIZED"
summaryStatusstring(BillRunSummaryStatus)

Bill run summary status

Enum"PROPERTIES""STARTING""REPORTING""DRAFT_INVOICES""FULL_INVOICES""DISTRIBUTION""DIRECT_DEBITS""ACCOUNTING_PACKAGES""COMBINING_INVOICES""CUSTOM_REPORTS"
billingUserAdminIdinteger(int64)read-only

Bill user who closed bill run

Example: 1
parallelbooleanrequired

Parallel bill run

revenueInMajorCurrencyinteger(int64)required

Revenue in this bill run now

Example: 1
usageSuspenseCountinteger(int64)required

Count of usage suspense records for this bill run now

Example: 1
rentalSuspenseCountinteger(int64)required

Count of rental suspense records for this bill run now

Example: 1
maxInvoiceValuenumber(decimal)

Highest value invoice in the bill run

maxInvoiceCustomerIdinteger(int64)

Customer Id

Example: 1
pausedboolean

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

replayablebooleanread-only

Flag to indicate if the bill run stage can be replayed or not. If true then the PATCH endpoint can be used to move the bill run to replay distribution summary states

Response
application/json
{
  "id": 1,
  "name": "string",
  "sortableName": "string",
  "billingCycleId": 1,
  "created": "2019-08-24",
  "periodStartDate": "2019-08-24",
  "periodEndDate": "2019-08-24",
  "invoiceDate": "2019-08-24",
  "includeUsageUntilDate": "2019-08-24",
  "billRunStatus": "OPEN",
  "summaryStatus": "PROPERTIES",
  "billingUserAdminId": 1,
  "parallel": true,
  "revenueInMajorCurrency": 1,
  "usageSuspenseCount": 1,
  "rentalSuspenseCount": 1,
  "maxInvoiceValue": 0,
  "maxInvoiceCustomerId": 1,
  "paused": true,
  "replayable": true
}

Update a specific bill run

Request

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

Security
bearerAuth
Path
bill_run_idinteger(int64)(IdParam)>= 1required

Bill run identifier

Example: 1
Bodyapplication/json-patch+jsonrequired

A set of JSONPatch operations to be performed

Array [
opstringrequired

The JSON Patch operation to be performed

Enum"add""remove""replace""move""copy""test"
pathstringrequired

A JSON-Pointer

valueobject

The value to be used within the operations

fromstring

A string containing a JSON Pointer value

]
curl -i -X PATCH \
  https://rest.elevatebilling.com/v1/bill-runs/1 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json-patch+json' \
  -d '[
    {
      "op": "replace",
      "path": "/billRunStatus",
      "value": "CLOSED"
    },
    {
      "op": "replace",
      "path": "/summaryStatus",
      "value": "REPORTING"
    },
    {
      "op": "replace",
      "path": "/invoiceDate",
      "value": "2023-02-04"
    }
  ]'

Responses

Success

Bodyapplication/json
idinteger(int64)read-only

Bill run identifier

Example: 1
namestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-onlyrequired

Bill run name

sortableNamestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-only

Sortable bill run name

billingCycleIdinteger(int64)required

Billing cycle Id

Example: 1
createdstring(date)read-only

Creation date

periodStartDatestring(date)required

Bill run start date

periodEndDatestring(date)required

Bill run end date

invoiceDatestring(date)required

The billing agent may wish a date that is different to appear on the invoice to manage customer perception.

includeUsageUntilDatestring(date)read-only

All the usage charges up to this date will be included as part of the bill run

billRunStatusstring(BillRunStatus)

Bill run status

Enum"OPEN""CLOSED""FINALIZED"
summaryStatusstring(BillRunSummaryStatus)

Bill run summary status

Enum"PROPERTIES""STARTING""REPORTING""DRAFT_INVOICES""FULL_INVOICES""DISTRIBUTION""DIRECT_DEBITS""ACCOUNTING_PACKAGES""COMBINING_INVOICES""CUSTOM_REPORTS"
billingUserAdminIdinteger(int64)read-only

Bill user who closed bill run

Example: 1
parallelbooleanrequired

Parallel bill run

revenueInMajorCurrencyinteger(int64)required

Revenue in this bill run now

Example: 1
usageSuspenseCountinteger(int64)required

Count of usage suspense records for this bill run now

Example: 1
rentalSuspenseCountinteger(int64)required

Count of rental suspense records for this bill run now

Example: 1
maxInvoiceValuenumber(decimal)

Highest value invoice in the bill run

maxInvoiceCustomerIdinteger(int64)

Customer Id

Example: 1
pausedboolean

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

replayablebooleanread-only

Flag to indicate if the bill run stage can be replayed or not. If true then the PATCH endpoint can be used to move the bill run to replay distribution summary states

Response
application/json
{
  "id": 1,
  "name": "string",
  "sortableName": "string",
  "billingCycleId": 1,
  "created": "2019-08-24",
  "periodStartDate": "2019-08-24",
  "periodEndDate": "2019-08-24",
  "invoiceDate": "2019-08-24",
  "includeUsageUntilDate": "2019-08-24",
  "billRunStatus": "OPEN",
  "summaryStatus": "PROPERTIES",
  "billingUserAdminId": 1,
  "parallel": true,
  "revenueInMajorCurrency": 1,
  "usageSuspenseCount": 1,
  "rentalSuspenseCount": 1,
  "maxInvoiceValue": 0,
  "maxInvoiceCustomerId": 1,
  "paused": true,
  "replayable": true
}

Adjust the schedule of the bill run by specified number of periods

Request

Security
bearerAuth
Path
bill_run_idinteger(int64)(IdParam)>= 1required

Bill run identifier

Example: 1
Query
periodsinteger(int32)required

Number of periods to adjust the start date of the bill run

Example: periods=1
curl -i -X POST \
  'https://rest.elevatebilling.com/v1/adjust-bill-run-schedule/1?periods=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Success

Bodyapplication/json
idinteger(int64)read-only

Bill run identifier

Example: 1
namestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-onlyrequired

Bill run name

sortableNamestring[ 1 .. 22 ] characters[a-zA-Z0-9\p{L}\s\+\/\-\._\&amp;#=,:@()]*read-only

Sortable bill run name

billingCycleIdinteger(int64)required

Billing cycle Id

Example: 1
createdstring(date)read-only

Creation date

periodStartDatestring(date)required

Bill run start date

periodEndDatestring(date)required

Bill run end date

invoiceDatestring(date)required

The billing agent may wish a date that is different to appear on the invoice to manage customer perception.

includeUsageUntilDatestring(date)read-only

All the usage charges up to this date will be included as part of the bill run

billRunStatusstring(BillRunStatus)

Bill run status

Enum"OPEN""CLOSED""FINALIZED"
summaryStatusstring(BillRunSummaryStatus)

Bill run summary status

Enum"PROPERTIES""STARTING""REPORTING""DRAFT_INVOICES""FULL_INVOICES""DISTRIBUTION""DIRECT_DEBITS""ACCOUNTING_PACKAGES""COMBINING_INVOICES""CUSTOM_REPORTS"
billingUserAdminIdinteger(int64)read-only

Bill user who closed bill run

Example: 1
parallelbooleanrequired

Parallel bill run

revenueInMajorCurrencyinteger(int64)required

Revenue in this bill run now

Example: 1
usageSuspenseCountinteger(int64)required

Count of usage suspense records for this bill run now

Example: 1
rentalSuspenseCountinteger(int64)required

Count of rental suspense records for this bill run now

Example: 1
maxInvoiceValuenumber(decimal)

Highest value invoice in the bill run

maxInvoiceCustomerIdinteger(int64)

Customer Id

Example: 1
pausedboolean

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

replayablebooleanread-only

Flag to indicate if the bill run stage can be replayed or not. If true then the PATCH endpoint can be used to move the bill run to replay distribution summary states

Response
application/json
{
  "id": 1,
  "name": "string",
  "sortableName": "string",
  "billingCycleId": 1,
  "created": "2019-08-24",
  "periodStartDate": "2019-08-24",
  "periodEndDate": "2019-08-24",
  "invoiceDate": "2019-08-24",
  "includeUsageUntilDate": "2019-08-24",
  "billRunStatus": "OPEN",
  "summaryStatus": "PROPERTIES",
  "billingUserAdminId": 1,
  "parallel": true,
  "revenueInMajorCurrency": 1,
  "usageSuspenseCount": 1,
  "rentalSuspenseCount": 1,
  "maxInvoiceValue": 0,
  "maxInvoiceCustomerId": 1,
  "paused": true,
  "replayable": true
}

adhoc-bill-runs

Operations