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. IBM and third-party service providers that are 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 service providers.

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 contain metrics that are accumulated over a small window of time. Depending on the metric, the accumulation window can be anywhere between 15 minutes to 24 hours. Service providers should ensure that the metrics are not accumulated with overlapping time windows. A usage record has the following fields.

Field Name Description
resource_instance_id The 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 value is specified in milliseconds since epoch.
end Time to which the usage was measured. This value 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 accumulated 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.

Guidelines

  • The start time and end time represent the time range during which the measures were collected, and they are not dependent on the time at which the usage record is submitted to the metering APIs.
  • Usage records are facts. After a usage record is created, its contents can't be altered. The metering service acknowledges with a location when a usage record is successfully created. If an error code is returned, see the error description for 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. After a usage record is processed, any other usage record with the same signature is rejected as a duplicate.
  • Usage records must be submitted within two days from the time at which the measurement was completed. Older usage records are rejected.

Submitting usage records

Metering supports submitting multiple usage records in one API call. A maximum of 100 usage records can be submitted per API call. When the HTTP response status code is 202, 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. See Error handling for the usage acceptance status codes and the necessary action that's required.

Best practices

  • All service providers must submit usage every hour so that the end user doesn't see a delay between the time that the resource was used and 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

Usage is always aggregated to the service plan and pricing plan. For example, your service might have a standard plan with a pricing plan of $0.80 per 1,000 API calls. Additional aggregations happen at the following three levels.

  1. Instance and consumer
  2. Resource group
  3. Account (Invoices are generated from the aggregated values in the account)

After an instance is provisioned, it has 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.

Endpoint

The Metering APIs are accessible using the host https://billing.cloud.ibm.com.

Error handling

HTTP status codes

HTTP Status Code Descriptions
400 The payload is in an incorrect format.
401 The IAM token that was used in the authorization header is invalid or expired.
403 The subject in the supplied token does not authorization to submit usage. Contact IBM representative to get access.
413 The number of usage records in the payload exceeds 100.
>=500 Resubmit the usage record. If problem persists, contact your IBM representative.

Usage acceptance status codes

Status Code Action Required
400 The usage record is not in a correct format. Possible reasons for this status include that the schema validation failed, the measures in the usage records are incorrect, or the start and end times do not fall between the provisioned and de-provisioned times. Fix the usage record and resubmit.
404 The metering definition has not been onboarded. Work with your IBM representative to check if the resource is onboarded, and resubmit the usage record.
409 The usage record is a duplicate. Do not retry.
424 The resource instance's metadata in the resource controller has some errors. Fix the resource instance details and resubmit usage.
>=500 Resubmit the usage record. If problem persists, contact your IBM representative.

Authentication

Access to the Usage Metering API is enforced through IBM Cloud Identity and Access Management (IAM) access tokens. Only access tokens that are associated with IAM service IDs can submit usage. The policy to submit usage is created by an IBM representative when you onboard your service.

Methods

Report Resource Controller resource usage

Report usage for resource instances that were provisioned through the resource controller.

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

Path Parameters

  • The resource for which the usage is submitted.

Usage information for a resource instance.

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.

  • The requesting service is unauthenticated.

  • The requesting service is not authorized to submit usage for the resource.

  • The resource definition was not found.

  • The payload is too large.

Example responses

Report Cloud Foundry resource usage

Report usage for resource instances that were provisioned by using the Cloud Foundry provisioning broker.

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

Path Parameters

  • The resource for which the usage is submitted.

Usage information for a Cloud Foundry resource instance.

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

  • The requesting service is unauthenticated.

  • The requesting service is not authorized to submit usage for the resource.

  • The resource definition was not found.

  • The payload is too large.

Example responses