Configure usage reporting to Google

If you choose usage-based pricing for your product, you must report your app's usage to the Service Control API.

For an introduction to Service Control, see the Getting Started Guide.

Before you begin

(For usage-based pricing) Report usage

When an entitlement is created, you must call the Partner Procurement API to retrieve a usageReportingId, using the following HTTP GET request:

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

The response contains information about the entitlement, in the following format:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

To report usage, you must first make a services.check API call, to check the service's configuration. In the response, if the checkErrors[] object is empty, make a services.report API call to send the usage report.

The usage report is a Service Control API Operation. The following is an example of a usage report for example-messaging-service that sends information about the storage being used by the customer:

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report

{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }],
    "userLabels": {
      "cloudmarketplace.googleapis.com/resource_name": "order_history_cache",
      "cloudmarketplace.googleapis.com/container_name": "storefront_prod",
      "environment": "prod",
      "region": "us-west2"
    }
  }]
}

where:

  • operationId is a unique string that your service instance generates. Use the same operationId for your check and report operations.
  • consumerId is the same as the usageReportingId from the entitlement.
  • startTime and endTime represent the start and end times of the total interval for the report Operation. In most cases, the startTime of a report Operation should have the same value as the endTime of the previous report Operation. If a customer's service is disabled before the startTime of a report Operation, the services.check API call sends an error in the checkErrors[] object, and the customer isn't charged for the corresponding interval.
  • MetricValueSet contains one or more intermediate time intervals and corresponding updated metric values. You define your service's metrics when you choose and submit your pricing model. You view and reference the identifiers for your metrics in the Technical integration section of Producer Portal.
  • userLabels are user-created labels, defined as key-value strings that follow specific syntax requirements. These labels are forwarded to Cloud Billing cost management tools for attribution. For recommendations related to usage labeling, see Best practices for usage labeling.

If the services.check API returns one or more of the following errors, we recommend that you stop providing your service to the customer until the error is resolved:

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED
Previous
Manage customer entitlements