How Metering API works

Overview on Metering API

Metering API is how IBM, partners, and clients submit usage data to IBM Software Central or Red Hat Marketplace. This data flows into customer dashboards and analytics services and facilitates billing for pay-as-you-go subscriptions.

Partner product onboarding and Metering API

During product onboarding, partners configure pricing for each paid edition. Pricing set-up includes defining billing frequency, subscription terms, and charge metrics. Using Metering API, partners send usage metrics and subscription plan information to the marketplace to help enable integrated billing and customer dashboards.

Partners with entitlements enabled for integrated billing must submit usage for all active instances every hour. Inability to report usage can lead to loss of revenue collection and revenue share for partners.

Partners should collect and send the following information on customer purchases through the marketplace:

• Usage metrics
• Subscription plan ID associated to usage metrics

Changes and version control for Metering API

Metering API adheres to the following change policy for minor versions:

• Existing endpoints and fields MUST NOT be removed or renamed.
• New OPTIONAL endpoints, or new HTTP methods for existing endpoints, MAY be added to enable support for new features.
• New fields MAY be added to existing request/response messages. These fields MUST be OPTIONAL and SHOULD be ignored by clients and servers that do not understand them.

Changes since latest release

• Initial Version - No changes being documented

Authentication

All communication will be over HTTPS with a self-signed certificate. All messages are authenticated using basic authentication. When authentication fails, partners must respond with 401 Unauthorized.

Authentication uses an Authorization header and the Bearer scheme.

Authorization: Bearer <token>

The token must be one of:

• A Pull Secret generated for an IBM Software Central or Red Hat Marketplace account
• An IBM Entitlement Key
• An access token

File upload API

The request is a multipart form-data request and consisting of a single application/gzip archive file. The archive file must contain a single manifest.json file at the root level.

If the archive file does not have the manifest.json file, or if the file exists but is invalid then no data from the archive will be processed.

The maximum size for the archive file is 1MiB.

Archive file structure

The archive will contain one manifest.json file and one or more data files that will be processed based on the type in the manifest file.

Manifest file content

{
    "version": "1",
    "type": "<manifest types>"
}

Data files

swcAccountMetrics type

This is the preferred type.

swcAccountMetrics properties will be defined in usage events and additional properties. They can either be a root level or measuredUsage level property, as shown in Additional properties.

Every file in the archive must be well-formed JSON with correct schema as described below. If any file in the archive is invalid then the entire archive will not be processed.

Example

{
  "data": [
    {
      "eventId": "unique guid per individual event",
      "start": 1485907200001,
      "end": 1485910800000,
      "accountId": "IBM Software Central or Red Hat Marketplace account id",
      "subscriptionId": "optionalValue",
      "productId": "sampleProductId",
      "productName": "IBM Cloud Pak for Data Enterprise Edition",
      "licensePartNumber": "part1234",
      "productType": "bundled or product",
      "source": "MCSP",
      "sourceSaas": "AWS, IBMCloud, etc",
      "accountIdSaas": "operationalSassAccountId",
      "subscriptionIdSaas": "20230414",
      "dswOfferAccountingSystemCode": "TRBO",
      "dswSubscriptionAgreementNumber": "string",
      "ssmSubscriptionId": "ssmSubsctriptionId",
      "sapEntitlementLine": "testEntitlement",
      "icn": "icnString",
      "group": "c8b82d189e03845.source.group.com",
      "groupName": "groupName",
      "kind": "IBMLicensing",
      "manual": "false",
      "parentProductId": "productIdOfParentProduct",
      "parentMetricId": "VIRTUAL_PROCESSOR_CORE",
      "topLevelProductId": "productIdOfTopLevelProduct",
      "topLevelMetricId": "VIRTUAL_PROCESSOR_CORE",
      "measuredUsage": [
        {
          "metricId": "metric id",
          "value": 8,
          "start": 1485907200001,
          "end": 1485910800000,
          "metricAggregationType": "cummulative",
          "metricType": "paygo",
          "crn": "crn:version:cname:ctype:service-name:location:scope:service-instance:resource-type:resource",
          "dedupCorrelationId": "optional-from-DRO-b2a7-d7ca4c5c76d4",
          "clusterId": "222222-6767-4c3a-xxxx-d7ca4c5c76d4",
          "hostname": "demo-metric-hostname-675b5dcff-cqj6n",
          "pod": "demo-metric-pod-cqj6n",
          "platformId": "platform-cqj6n",
          "namespace": "namespace1",
          "meter_def_namespace": "namespace1",
          "measuredMetricId": "VIRTUAL_PROCESSOR_CORE",
          "measuredValue": "7",
          "productConversionRatio": "3:1"
        }
      ]
    }
  ],
  "metadata": {}
}

accountMetrics type

The accountMetrics type is for product usage metrics for an IBM Software Central or Red Hat Marketplace account. Every file in the archive must be well-formed JSON with correct schema as described below. If any file in the archive is invalid then the entire archive will not be processed.

Example

{
  "data": [
    {
      "eventId": "unique guid per individual event",
      "start": <UTC milliseconds timestamp>,
      "end": <UTC milliseconds timestamp>,
      "accountId": "IBM Software Central or Red Hat Marketplace account id"
      "additionalAttributes": {},
      "measuredUsage": [
        {
          "metricId": "metric id",
          "value": <numeric value>,
          "additionalAttributes": {}
        }
      ]
    }
  ],
  "metadata": {}
}

Account metrics file properties

Usage event properties

Measured usage properties

Additional properties

These properties provide additional information about the usage. They are all initially optional, but the value of one property may influence the values that other properties can or must have. Unknown properties must have no effect on processing, but they will be saved. All property values are strings.

In swcAccountMetrics, properties can either appear as root properties or as properties under measuredUsage. The swcAccountMetrics column in the table below illustrates which properties belong in root or measuredUsage.

In accountMetrics they can appear in an additionalAttributes field at either the root or measuredUsage level. The accountMetrics column in the table below describes which additionalAttributes each property can appear in. “either” in this column means it can appear in either the root level additionalAttributes or in the measuredUsage addtionalAttributes.

Metric types

Metric aggregation types

Product types

dataReporter type

Data reporter type data is sent to Segment without further processing.

Example

{
  "data": [],
  "metadata" {}
}

Data reporter file properties

Responses

Metering API responds with the following HTTP codes.

Retries

Retries for internal and downstream errors will be processed automatically by the system. Errors in submitted data can be fixed by submitting an amendment. Refer to “Amend usage”.

Amend usage

Submitted data can be amended by submitting revised data with the same eventId in a new request. Amendments must have the same group, kind, and subscriptionId as their original usage event. They must also have the same number or fewer measuredUsages as their original usage event, and any metricIds present in measuredUsages in the amendment must have been present in the original usage event. Amendments are processed by completely replacing the data in the original usage event with the data in the amendment per measuredUsage. A measuredUsage present in the original usage event but not present in the amendment will be unchanged. Submitting an amendment where the value for a measuredUsage is 0 will effectively delete that metric.

Metering API reference

For details on methods, endpoints, requests, and responses, refer to Metering API reference.