Usage

Use these operations to manage the product usage of a subscription item for metered billing purposes.

Use metered billing when product quantity is unknown to the customer at the moment of creating a subscription. Metered billing is based on reported usage records. Every reported usage updates the quantity of an upcoming invoice item for a specified subscription and a plan. To create a metered billing plan, see Plans.

Operations

Retrieve usage records

Request

Retrieves a list of usage records.

Security
SecretApiKey or JWT
Query
filterstring

Criteria for filtering collection items. This field requires a special format. Use , to specify multiple allowed values. Use ; to specify multiple fields.

For more information, see Search filters.

sortArray of strings

Sorts and orders the collection of items. To sort in descending order, prefix with -. Multiple fields can be sorted by separating each with ,.

limitinteger, [ 0 .. 1000 ]

Limits the number of collection items to be returned.

offsetinteger, [ 0 .. 1000 ]

Specifies the starting point within the collection of items to be returned.

qstring

Use this field to perform a partial search of text fields.

curl -i -X GET \
  'https://www.rebilly.com/_mock/catalog/all/usages?filter=string&sort=string&limit=1000&offset=1000&q=string' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE'

Responses

List of usage records retrieved.

Headers
Pagination-Totalinteger

Total number of items.

Example:332
Pagination-Limitinteger

Maximum number of items per page.

Example:100
Pagination-Offsetinteger

Specifies the starting point within the collection of resource results. For example, a request with limit=20 retrieves and displays the first 20 results on a page. A following request with limit=20 and offset=20, retrieves the next page of 20 results.

Example:2
Bodyapplication/json
Array [
idstring, <= 50 charactersread-only

ID of the usage record.

Example:"sub_usg_0YVJ636B95DNA9M3B1638HXBCQ"
subscriptionIdstring, <= 50 charactersrequired

Subscription ID for which the usage is reported.

Example:"sub_01HRF27SATGE4Z6PBJE6PD8328"
invoiceIdstring or null, <= 50 charactersread-only

ID of the invoice to which usage is applied. This value is populated when the invoice is issued.

Example:"in_0YVF9605RKC62BP14NE2R7V2XT"
invoiceItemIdstring or null, <= 50 charactersread-only

ID of the invoice item to which usage is applied. This value is populated when the invoice is issued.

Example:"ii_0YVFDEQS2KCFTBN9HXWJFY55GV"
quantitynumber, (double), >= 0.001required

Quantity of consumed units for a subscription plan product. Represents the actual usage of a billable product or service by the customer. Accepts both integer and decimal values with a precision of up to 3 decimal places. The minimum billable unit is 0.001.

Example:5.125
usageTimestring, (date-time)

Date and time, in ISO 8601 format, when a usage occurred. If this value is not provided or is empty, the date and time of the request is used.

createdTimestring, (date-time)(CreatedTime)read-only

Date and time when the resource is created. This value is set automatically when the resource is created.

updatedTimestring, (date-time)(UpdatedTime)read-only

Date and time when the resource is updated. This value is set automatically when the resource is updated.

]
Response
[
  {
    "id": "sub_usg_0YVJ636B95DNA9M3B1638HXBCQ",
    "subscriptionId": "sub_01HRF27SATGE4Z6PBJE6PD8328",
    "invoiceId": "in_0YVF9605RKC62BP14NE2R7V2XT",
    "invoiceItemId": "ii_0YVFDEQS2KCFTBN9HXWJFY55GV",
    "quantity": 5.125,
    "usageTime": "2019-08-24T14:15:22Z",
    "createdTime": "2019-08-24T14:15:22Z",
    "updatedTime": "2019-08-24T14:15:22Z",
    "_links": [ … ]
  }
]