Skip to content
/
Check if an inclusive usa...

Elevate Pricing API (2.21)

Usage and Rental Pricing Management

Provides read & write access to usage and rental rate cards and inclusive usage plans

Definitions

  • Usage Rate Card - a representation of the pricing structure for usage that can be sold to Customers, for example 5 pence per minute for UK National calls
  • Rental Rate Card - a representation of the pricing structure for rental product that can be sold to Customers, for example £10 per month for line rental
  • Inclusive Usage Plan - a representation of an inclusive bundle that can be sold to a Customer, for example you can allocate 500 free minutes to UK National or Local calls
Download OpenAPI description
billing-rest-pricing.json
billing-rest-pricing.yaml
Languages
Servers
https://rest.elevatebilling.com/v2

usage-rate-cards

Usage rate cards represent the pricing structure for usage products that can be sold to Customers

Operations

usage-rates

Usage rates represent the pricing rates for a usage product

Operations

rental-rate-cards

Rental rates card represent the pricing structure for rental products that can be sold to Customers

Operations

rental-rates

Rental rates represent the pricing rates for a rental product

Operations

inclusive-usage-plans

Inclusive usage plans represent an inclusive bundle that can be sold to Customers

Operations

Get a list of available inclusive usage plans

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
contractOwnerIdstring(IdFilterParam)

Filter by contract Owner

Example: contractOwnerId=0
namestring(StringFilterParam)

Filter by name

Example: name=xyz | in:x,y | like:xyz
availableFromstring(DateFilterParam)

Filter by available from date

Example: availableFrom=yyyy-MM-dd | lt:yyyy-MM-dd | gt:yyyy-MM-dd | gtn:yyyy-MM-dd
availableTostring(DateFilterParam)

Filter by available to date

Example: availableTo=yyyy-MM-dd | lt:yyyy-MM-dd | gt:yyyy-MM-dd | gtn:yyyy-MM-dd
usageProductIdstring(IdFilterParam)

Filter by usage product

Example: usageProductId=0
taxBandIdstring(IdFilterParam)

Filter by tax band

Example: taxBandId=0
Headers
summarystring(BooleanFilterParam)

If true, returns a lightweight summary of each inclusive usage plan instead of the full object. Use this to reduce payload size and improve performance when only basic information is needed.

Example: true | false
curl -i -X GET \
  'https://rest.elevatebilling.com/v2/inclusive-usage-plans?page=1&pageSize=100&sort=id%2Cname+%7C+name%3Adesc&fields=id%2Cname&contractOwnerId=0&name=xyz+%7C+in%3Ax%2Cy+%7C+like%3Axyz&availableFrom=yyyy-MM-dd+%2C+lt%3Ayyyy-MM-dd+%2C+gt%3Ayyyy-MM-dd+%2C+gtn%3Ayyyy-MM-dd&availableTo=yyyy-MM-dd+%2C+lt%3Ayyyy-MM-dd+%2C+gt%3Ayyyy-MM-dd+%2C+gtn%3Ayyyy-MM-dd&usageProductId=0&taxBandId=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'summary: true | false'

Responses

OK

Bodyapplication/jsonArray [
idinteger(int64)read-only

Inclusive usage plan identifier

Example: 1
contractOwnerIdinteger(int32)required

Contract owner identifier

Example: 1
namestring[ 1 .. 100 ] characters[\w\p{L}\s%£@&#=':;`’,|!_—–\(\)\\/\-\+\.\?\*\...required

Inclusive usage plan name

usageProductIdinteger(int64)required

Usage product identifier

Example: 1
availableFromstring(date)required

Available from date

availableTostring(date)

Available to date

boltOnboolean

Bolt on flag

Default false
taxBandIdinteger(int64)

Tax band identifier

nominalCodestring[ 1 .. 100 ] characters^[\w\p{L}\s%£@&#=':;,`’|!_—–()/\-+.?*$\[\]€^{...

Nominal code

Example: "SALES-01QTR2"
inclusiveUsageComponentsArray of objects(InclusiveUsage)
boltOnChargesArray of objects(InclusiveUsageBoltOnCharge)
rolloverPeriodsinteger(int64)

Roll over period

triggerChargeIdinteger(int64)

The first qualifying inclusive usage event will trigger a charge using the selected rental product (an RPI will be created). If the allowance is used up, the next qualifying event will trigger another charge

Example: 1
supplierAccountIdinteger(int64)

The supplier account associated with the triggered rental product based on the rental product's supplier (required when trigger charge is set)

Example: 1
frequencystring(InclusiveUsageFrequency)

Frequency or period for the inclusive usage plan. This can be daily, weekly or monthly (required when trigger charge is set)

Enum"MONTHLY""DAILY""WEEKLY"
minQualifyingQuantitynumber

If required, specify the minimum quantity required for an event to qualify for deduction from the inclusive usage allowance. E.g. rate events as normal if the qty is less than this value but deduct from the allowance if equal to or greater than this value. Only applicable for inclusive usage components that are quantity based (duration/megabyte/one-off)

maxPerEventQuantitynumber

Events over this quantity will be split such that the first part of the event is deducted from the inclusive usage allowance while the latter part is rated as normal. Leave this value as "0" to ignore this functionality and qualify the whole event for inclusive usage rating

]
Response
application/json
[
  {
    "id": 1,
    "contractOwnerId": 1,
    "name": "string",
    "usageProductId": 1,
    "availableFrom": "2019-08-24",
    "availableTo": "2019-08-24",
    "boltOn": false,
    "taxBandId": 0,
    "nominalCode": "SALES-01QTR2",
    "inclusiveUsageComponents": [ … ],
    "boltOnCharges": [ … ],
    "rolloverPeriods": 0,
    "triggerChargeId": 1,
    "supplierAccountId": 1,
    "frequency": "MONTHLY",
    "minQualifyingQuantity": 0,
    "maxPerEventQuantity": 0
  }
]

Check if an inclusive usage plan exists

Request

Security
bearerAuth
Query
idstring(IdFilterParam)

Filter by id

Example: id=0
contractOwnerIdstring(IdFilterParam)

Filter by contract Owner

Example: contractOwnerId=0
namestring(StringFilterParam)

Filter by name

Example: name=xyz | in:x,y | like:xyz
availableFromstring(DateFilterParam)

Filter by available from date

Example: availableFrom=yyyy-MM-dd | lt:yyyy-MM-dd | gt:yyyy-MM-dd | gtn:yyyy-MM-dd
availableTostring(DateFilterParam)

Filter by available to date

Example: availableTo=yyyy-MM-dd | lt:yyyy-MM-dd | gt:yyyy-MM-dd | gtn:yyyy-MM-dd
usageProductIdstring(IdFilterParam)

Filter by usage product

Example: usageProductId=0
taxBandIdstring(IdFilterParam)

Filter by tax band

Example: taxBandId=0
curl -i -X HEAD \
  'https://rest.elevatebilling.com/v2/inclusive-usage-plans?id=0&contractOwnerId=0&name=xyz+%7C+in%3Ax%2Cy+%7C+like%3Axyz&availableFrom=yyyy-MM-dd+%2C+lt%3Ayyyy-MM-dd+%2C+gt%3Ayyyy-MM-dd+%2C+gtn%3Ayyyy-MM-dd&availableTo=yyyy-MM-dd+%2C+lt%3Ayyyy-MM-dd+%2C+gt%3Ayyyy-MM-dd+%2C+gtn%3Ayyyy-MM-dd&usageProductId=0&taxBandId=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Body

Create a new inclusive usage plan

Request

Security
bearerAuth
Bodyapplication/jsonrequired

New Inclusive Usage Plan

contractOwnerIdinteger(int32)required

Contract owner identifier

Example: 1
namestring[ 1 .. 100 ] characters[\w\p{L}\s%£@&#=':;`’,|!_—–\(\)\\/\-\+\.\?\*\...required

Inclusive usage plan name

usageProductIdinteger(int64)required

Usage product identifier

Example: 1
availableFromstring(date)required

Available from date

availableTostring(date)

Available to date

boltOnboolean

Bolt on flag

Default false
taxBandIdinteger(int64)

Tax band identifier

nominalCodestring[ 1 .. 100 ] characters^[\w\p{L}\s%£@&#=':;,`’|!_—–()/\-+.?*$\[\]€^{...

Nominal code

Example: "SALES-01QTR2"
inclusiveUsageComponentsArray of objects(InclusiveUsage)
boltOnChargesArray of objects(InclusiveUsageBoltOnCharge)
rolloverPeriodsinteger(int64)

Roll over period

triggerChargeIdinteger(int64)

The first qualifying inclusive usage event will trigger a charge using the selected rental product (an RPI will be created). If the allowance is used up, the next qualifying event will trigger another charge

Example: 1
supplierAccountIdinteger(int64)

The supplier account associated with the triggered rental product based on the rental product's supplier (required when trigger charge is set)

Example: 1
frequencystring(InclusiveUsageFrequency)

Frequency or period for the inclusive usage plan. This can be daily, weekly or monthly (required when trigger charge is set)

Enum"MONTHLY""DAILY""WEEKLY"
minQualifyingQuantitynumber

If required, specify the minimum quantity required for an event to qualify for deduction from the inclusive usage allowance. E.g. rate events as normal if the qty is less than this value but deduct from the allowance if equal to or greater than this value. Only applicable for inclusive usage components that are quantity based (duration/megabyte/one-off)

maxPerEventQuantitynumber

Events over this quantity will be split such that the first part of the event is deducted from the inclusive usage allowance while the latter part is rated as normal. Leave this value as "0" to ignore this functionality and qualify the whole event for inclusive usage rating

curl -i -X POST \
  https://rest.elevatebilling.com/v2/inclusive-usage-plans \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contractOwnerId": 1,
    "name": "string",
    "usageProductId": 1,
    "availableFrom": "2019-08-24",
    "availableTo": "2019-08-24",
    "boltOn": false,
    "taxBandId": 0,
    "nominalCode": "SALES-01QTR2",
    "inclusiveUsageComponents": [
      {
        "description": "string",
        "componentType": "VALUE",
        "chargingType": "DURATION",
        "quantity": 0,
        "valueInPence": 0,
        "timebands": [
          {
            "timeband": "PEAK"
          }
        ],
        "chargeGroups": [
          {
            "chargeGroupId": 0
          }
        ],
        "chargeGroupCategories": [
          {
            "chargeGroupCategoryId": 0
          }
        ],
        "dialStrings": [
          {
            "dialString": "string",
            "isWholeNumber": true
          }
        ]
      }
    ],
    "boltOnCharges": [
      {
        "price": 0,
        "rentalRateType": "ADVANCE",
        "periodsInAdvance": "STANDARD",
        "rentalRateFrequency": "DAILY",
        "showOnInvoice": true,
        "startDate": "2019-08-24",
        "endDate": "2019-08-24"
      }
    ],
    "rolloverPeriods": 0,
    "triggerChargeId": 1,
    "supplierAccountId": 1,
    "frequency": "MONTHLY",
    "minQualifyingQuantity": 0,
    "maxPerEventQuantity": 0
  }'

Responses

OK

Bodyapplication/json
idinteger(int64)read-only

Inclusive usage plan identifier

Example: 1
contractOwnerIdinteger(int32)required

Contract owner identifier

Example: 1
namestring[ 1 .. 100 ] characters[\w\p{L}\s%£@&#=':;`’,|!_—–\(\)\\/\-\+\.\?\*\...required

Inclusive usage plan name

usageProductIdinteger(int64)required

Usage product identifier

Example: 1
availableFromstring(date)required

Available from date

availableTostring(date)

Available to date

boltOnboolean

Bolt on flag

Default false
taxBandIdinteger(int64)

Tax band identifier

nominalCodestring[ 1 .. 100 ] characters^[\w\p{L}\s%£@&#=':;,`’|!_—–()/\-+.?*$\[\]€^{...

Nominal code

Example: "SALES-01QTR2"
inclusiveUsageComponentsArray of objects(InclusiveUsage)
boltOnChargesArray of objects(InclusiveUsageBoltOnCharge)
rolloverPeriodsinteger(int64)

Roll over period

triggerChargeIdinteger(int64)

The first qualifying inclusive usage event will trigger a charge using the selected rental product (an RPI will be created). If the allowance is used up, the next qualifying event will trigger another charge

Example: 1
supplierAccountIdinteger(int64)

The supplier account associated with the triggered rental product based on the rental product's supplier (required when trigger charge is set)

Example: 1
frequencystring(InclusiveUsageFrequency)

Frequency or period for the inclusive usage plan. This can be daily, weekly or monthly (required when trigger charge is set)

Enum"MONTHLY""DAILY""WEEKLY"
minQualifyingQuantitynumber

If required, specify the minimum quantity required for an event to qualify for deduction from the inclusive usage allowance. E.g. rate events as normal if the qty is less than this value but deduct from the allowance if equal to or greater than this value. Only applicable for inclusive usage components that are quantity based (duration/megabyte/one-off)

maxPerEventQuantitynumber

Events over this quantity will be split such that the first part of the event is deducted from the inclusive usage allowance while the latter part is rated as normal. Leave this value as "0" to ignore this functionality and qualify the whole event for inclusive usage rating

Response
application/json
{
  "id": 1,
  "contractOwnerId": 1,
  "name": "string",
  "usageProductId": 1,
  "availableFrom": "2019-08-24",
  "availableTo": "2019-08-24",
  "boltOn": false,
  "taxBandId": 0,
  "nominalCode": "SALES-01QTR2",
  "inclusiveUsageComponents": [
    { … }
  ],
  "boltOnCharges": [
    { … }
  ],
  "rolloverPeriods": 0,
  "triggerChargeId": 1,
  "supplierAccountId": 1,
  "frequency": "MONTHLY",
  "minQualifyingQuantity": 0,
  "maxPerEventQuantity": 0
}

Get a specific inclusive usage plan

Request

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

Inclusive usage plan identifier

Example: 1
curl -i -X GET \
  https://rest.elevatebilling.com/v2/inclusive-usage-plans/1 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Inclusive usage plan found

Bodyapplication/json
idinteger(int64)read-only

Inclusive usage plan identifier

Example: 1
contractOwnerIdinteger(int32)required

Contract owner identifier

Example: 1
namestring[ 1 .. 100 ] characters[\w\p{L}\s%£@&#=':;`’,|!_—–\(\)\\/\-\+\.\?\*\...required

Inclusive usage plan name

usageProductIdinteger(int64)required

Usage product identifier

Example: 1
availableFromstring(date)required

Available from date

availableTostring(date)

Available to date

boltOnboolean

Bolt on flag

Default false
taxBandIdinteger(int64)

Tax band identifier

nominalCodestring[ 1 .. 100 ] characters^[\w\p{L}\s%£@&#=':;,`’|!_—–()/\-+.?*$\[\]€^{...

Nominal code

Example: "SALES-01QTR2"
inclusiveUsageComponentsArray of objects(InclusiveUsage)
boltOnChargesArray of objects(InclusiveUsageBoltOnCharge)
rolloverPeriodsinteger(int64)

Roll over period

triggerChargeIdinteger(int64)

The first qualifying inclusive usage event will trigger a charge using the selected rental product (an RPI will be created). If the allowance is used up, the next qualifying event will trigger another charge

Example: 1
supplierAccountIdinteger(int64)

The supplier account associated with the triggered rental product based on the rental product's supplier (required when trigger charge is set)

Example: 1
frequencystring(InclusiveUsageFrequency)

Frequency or period for the inclusive usage plan. This can be daily, weekly or monthly (required when trigger charge is set)

Enum"MONTHLY""DAILY""WEEKLY"
minQualifyingQuantitynumber

If required, specify the minimum quantity required for an event to qualify for deduction from the inclusive usage allowance. E.g. rate events as normal if the qty is less than this value but deduct from the allowance if equal to or greater than this value. Only applicable for inclusive usage components that are quantity based (duration/megabyte/one-off)

maxPerEventQuantitynumber

Events over this quantity will be split such that the first part of the event is deducted from the inclusive usage allowance while the latter part is rated as normal. Leave this value as "0" to ignore this functionality and qualify the whole event for inclusive usage rating

Response
application/json
{
  "id": 1,
  "contractOwnerId": 1,
  "name": "string",
  "usageProductId": 1,
  "availableFrom": "2019-08-24",
  "availableTo": "2019-08-24",
  "boltOn": false,
  "taxBandId": 0,
  "nominalCode": "SALES-01QTR2",
  "inclusiveUsageComponents": [
    { … }
  ],
  "boltOnCharges": [
    { … }
  ],
  "rolloverPeriods": 0,
  "triggerChargeId": 1,
  "supplierAccountId": 1,
  "frequency": "MONTHLY",
  "minQualifyingQuantity": 0,
  "maxPerEventQuantity": 0
}

Patch update inclusive usage plan

Request

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

Inclusive usage plan identifier

Example: 1
Headers
summarystring(BooleanFilterParam)

If true, returns a lightweight summary of inclusive usage plan instead of the full object. Use this to reduce payload size and improve performance when only basic information is needed.

Example: true | false
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/v2/inclusive-usage-plans/1 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'summary: true | false' \
  -d '[
    {
      "op": "replace",
      "path": "/name",
      "value": "My Plan"
    }
  ]'

Responses

OK

Bodyapplication/json
idinteger(int64)read-only

Inclusive usage plan identifier

Example: 1
contractOwnerIdinteger(int32)required

Contract owner identifier

Example: 1
namestring[ 1 .. 100 ] characters[\w\p{L}\s%£@&#=':;`’,|!_—–\(\)\\/\-\+\.\?\*\...required

Inclusive usage plan name

usageProductIdinteger(int64)required

Usage product identifier

Example: 1
availableFromstring(date)required

Available from date

availableTostring(date)

Available to date

boltOnboolean

Bolt on flag

Default false
taxBandIdinteger(int64)

Tax band identifier

nominalCodestring[ 1 .. 100 ] characters^[\w\p{L}\s%£@&#=':;,`’|!_—–()/\-+.?*$\[\]€^{...

Nominal code

Example: "SALES-01QTR2"
inclusiveUsageComponentsArray of objects(InclusiveUsage)
boltOnChargesArray of objects(InclusiveUsageBoltOnCharge)
rolloverPeriodsinteger(int64)

Roll over period

triggerChargeIdinteger(int64)

The first qualifying inclusive usage event will trigger a charge using the selected rental product (an RPI will be created). If the allowance is used up, the next qualifying event will trigger another charge

Example: 1
supplierAccountIdinteger(int64)

The supplier account associated with the triggered rental product based on the rental product's supplier (required when trigger charge is set)

Example: 1
frequencystring(InclusiveUsageFrequency)

Frequency or period for the inclusive usage plan. This can be daily, weekly or monthly (required when trigger charge is set)

Enum"MONTHLY""DAILY""WEEKLY"
minQualifyingQuantitynumber

If required, specify the minimum quantity required for an event to qualify for deduction from the inclusive usage allowance. E.g. rate events as normal if the qty is less than this value but deduct from the allowance if equal to or greater than this value. Only applicable for inclusive usage components that are quantity based (duration/megabyte/one-off)

maxPerEventQuantitynumber

Events over this quantity will be split such that the first part of the event is deducted from the inclusive usage allowance while the latter part is rated as normal. Leave this value as "0" to ignore this functionality and qualify the whole event for inclusive usage rating

Response
application/json
{
  "id": 1,
  "contractOwnerId": 1,
  "name": "string",
  "usageProductId": 1,
  "availableFrom": "2019-08-24",
  "availableTo": "2019-08-24",
  "boltOn": false,
  "taxBandId": 0,
  "nominalCode": "SALES-01QTR2",
  "inclusiveUsageComponents": [
    { … }
  ],
  "boltOnCharges": [
    { … }
  ],
  "rolloverPeriods": 0,
  "triggerChargeId": 1,
  "supplierAccountId": 1,
  "frequency": "MONTHLY",
  "minQualifyingQuantity": 0,
  "maxPerEventQuantity": 0
}

inclusive-usage-balances

Inclusive usage balances represent the current balance of an inclusive usage plan for a Customer, Site or Inventory

Operations