Introduction

IBM Cloud Usage Metering is a platform service that enables service providers to submit metrics collected for resource instances provisioned by IBM Cloud users. Third-party service providers delivering an Integrated billing service in IBM Cloud are required to submit usage for all active service instances every hour. This is important because inability to report usage can lead to loss of revenue collection for IBM, in turn causing loss of revenue share for the third-party service provider.

Prerequisites

  • You must be approved to deliver an integrated billing service in IBM Cloud
  • You must have a registered service in the resource management console
  • Your pricing plan must be successfully published to the IBM Cloud catalog, and updated with prices for all chargeable metrics in the plans of the resource.
  • Metering and rating definitions for all the plans in the resource have been verified.

Usage records

Usage records are the smallest entities that contribute to the aggregated values of the metrics. A usage record is constructed using the following fields

Field Name Description
resource_instance_id ID of the resource instance as registered in the resource controller (The IBM Cloud provisioning layer)
plan_id The contract by which the usage record should be aggregated and rated
start Time from which the usage was measured. This is specified in milliseconds since epoch
end Time to which the usage was measured. This is specified in milliseconds since epoch
region The service provider region in which the usage was measured
measured_usage An array of measures with its values
consumer_id Optional field. If aggregation is required at a consumer level then this field is required. Having a value for consumer_id for any other reason might result in incorrect aggregation. The consumer_id is known only to the service provider.

Submitting Usage Records

Metering supports submitting multiple usage records in one API call. A maximum of 100 usage records can be submitted per call. The response body will include the acceptance status of every usage record. Any status other than 201 is accompanied with an error code and indicates that there is some problem with the usage record and was not accepted. The following table lists the status codes and the necessary action that's required.

Guidelines

  • The start time and end time represent the time range during which the measures were collected and it is not dependent on the time at which the usage record is submitted to the metering APIs.

    • Usage records are facts. Once a usage record is created, its contents should not be altered. The metering service acknowledges with a location when a usage record has been successfully created. If an error code is returned then please refer to the actions that you might have to take.

    • A usage record is uniquely identified by the signature account_id/resource_group_id/resource_instance_id/consumer_id/plan_id/region/start/end. Once a usage record is processed, any other usage record with the same signature is rejected as a duplicate.

    • Usage records should be submitted within 2 days from the time at which the measurement was completed. Older usage records are rejected.

Best Practices

  • All service providers must submit usage every 1 hour so that the end user does not see a delay between the time that the resource was consumed to the time that the cost is reflected in their accounts.

  • Retry submission of usage records only if there was a genuine failure with the previous request. Do not resubmit usage records that were successfully accepted.

Aggregation Levels

Aggregation is always to the plan + pricing plan. Aggregations happen at three levels.

  1. Instance + Consumer
  2. Resource Group
  3. Account (Invoices are generated from the aggregated values in the account)

An instance once provisioned will have the same pricing plan for the entire billing period (month). The pricing plan is determined based on the date on which the instance is provisioned.

Error handling

Status Code Action required
>=500 Retry submission. If problem persists, contact your IBM representative
400 The usage record is not in correct format. Either the schema validation has failed, or the measures in the usage records are incorrect or the start and end times does not fall between the provisioned and de-provisioned times. Fix the usage record and re-submit.
424 The resource instance's metadata in the resource controller has someissues. Fix the resource instance details and resubmit usage.
404 The metering definition has not been on-boarded. Work with your IBM representative to check if the resource is on-boarded and resubmit the usage record.
409 The usage record is a duplicate. Do not retry.

Methods

Resource Usage

Report usage for resource instances

POST /v4/metering/resources/{resource_id}/usage
Request

Custom Headers

  • IAM Token of the resource provider with authorization to submit usage for the resource specified in resource_id parameter. This value is not your IAM service name, it is your IAM operator service ID. You can find this value in the IAM Operator Service ID field in the RMC - IAM page.

Path Parameters

  • Resource for which the usage is submitted

Example:
Response

Response when usage submitted is accepted

Status Code

  • Indicates that the submitted payload was successfully stored. The status of indvidual usage records are available as a part of the resources array and it has one to one correspondence with the usage records in the payload. A status value of 201 indicates that they will be rated and any other value indicates a failure.

  • Schema validation failed for the payload

  • Unauthenticated

  • User is not authorized to submit usage for the resource

  • Resource definition not found

  • Payload is too large

Example responses