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
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:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[],[],null,["# Configure usage reporting to Google\n\nIf you choose usage-based pricing for your product, you must report your app's\nusage to the\n[Service Control API](/service-infrastructure/docs/overview).\n\nFor an introduction to Service Control, see the\n[Getting Started Guide](/service-infrastructure/docs/service-control/getting-started).\n\nBefore you begin\n----------------\n\n- Set up access to the Cloud Commerce Partner Procurement API, as described in [Integrate your app](/marketplace/docs/partners/integrated-saas/technical-integration-setup).\n- We recommend that you use Producer Portal to [create a service account](/marketplace/docs/partners/integrated-saas/backend-integration#producer-portal-service-accounts)for use with Service Control.\n\n(For usage-based pricing) Report usage\n--------------------------------------\n\nWhen an entitlement is created, you must call the Partner Procurement API\nto retrieve a `usageReportingId`, using the following `HTTP GET` request: \n\n```\nGET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID\n```\n\nThe response contains information about the entitlement, in the following\nformat: \n\n```json\n{\n \"name\": \"providers/\u003cvar translate=\"no\"\u003eYOUR_PARTNER_ID\u003c/var\u003e/entitlements/\u003cvar translate=\"no\"\u003eENTITLEMENT_ID\u003c/var\u003e\",\n \"provider\": \"\u003cvar translate=\"no\"\u003eYOUR_PARTNER_ID\u003c/var\u003e\",\n \"account\": \"\u003cvar translate=\"no\"\u003eUSER_ACCOUNT_ID\u003c/var\u003e\",\n \"product\": \"example-messaging-service\",\n \"plan\": \"pro\",\n \"usageReportingId\": \"\u003cvar translate=\"no\"\u003eUSAGE_REPORTING_ID\u003c/var\u003e\",\n \"state\": \"ENTITLEMENT_ACTIVATION_REQUESTED\",\n \"updateTime\": \"...\",\n \"createTime\": \"...\"\n}\n```\n\nTo report usage, you must first make a\n[`services.check`](/service-infrastructure/docs/service-control/reference/rest/v1/services/check)\nAPI call, to check the service's configuration. In the response, if the\n`checkErrors[]` object is empty, make a\n[`services.report`](/service-infrastructure/docs/service-control/reference/rest/v1/services/report)\nAPI call to send the usage report.\n| **Caution:** To avoid large unexpected charges, test usage-based reporting with small amounts of usage (less than $100 USD) per Cloud Billing account in that Cloud Billing account's currency.\n\nThe usage report is a Service Control API\n[`Operation`](/service-infrastructure/docs/service-control/reference/rest/v1/Operation).\nThe following is an example of a usage report for `example-messaging-service`\nthat sends information about the storage being used by the customer: \n\n```\nPOST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report\n``` \n\n```json\n{\n \"operations\": [{\n \"operationId\": \"1234-example-operation-id-4567\",\n \"operationName\": \"Hourly Usage Report\",\n \"consumerId\": \"\u003cvar translate=\"no\"\u003eUSAGE_REPORTING_ID\u003c/var\u003e\",\n \"startTime\": \"2019-02-06T12:00:00Z\",\n \"endTime\": \"2019-02-06T13:00:00Z\",\n \"metricValueSets\": [{\n \"metricName\": \"example-messaging-service/UsageInGiB\",\n \"metricValues\": [{ \"int64Value\": \"150\" }]\n }],\n \"userLabels\": {\n \"cloudmarketplace.googleapis.com/resource_name\": \"order_history_cache\",\n \"cloudmarketplace.googleapis.com/container_name\": \"storefront_prod\",\n \"environment\": \"prod\",\n \"region\": \"us-west2\"\n }\n }]\n}\n```\n\nwhere:\n\n- `operationId` is a unique string that your service instance generates. Use the same `operationId` for your `check` and `report` operations.\n- `consumerId` is the same as the `usageReportingId` from the entitlement.\n- `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.\n- [`MetricValueSet`](/service-infrastructure/docs/service-control/reference/rest/v1/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](/marketplace/docs/partners/integrated-saas/select-pricing). You view and reference the identifiers for your metrics in the **Technical integration** section of Producer Portal.\n- `userLabels` are user-created labels, defined as key-value strings that follow specific [syntax requirements](/resource-manager/docs/creating-managing-labels#requirements). These labels are forwarded to Cloud Billing [cost management](/cost-management) tools for attribution. For recommendations related to usage labeling, see [Best practices for usage labeling](/marketplace/docs/partners/integrated-saas/best-practices-labeling).\n\nIf the `services.check` API returns one or more of the following errors, we\nrecommend that you stop providing your service to the customer until the error\nis resolved:\n\n- `SERVICE_NOT_ACTIVATED`\n- `BILLING_DISABLED`\n- `PROJECT_DELETED`"]]