Skip to main content
More in Learn

Tracking Usage for Metered Subscriptions

For subscription contracts that involve one or more metered variables–number of users or bandwidth, for instance–you need to log how much each customer is using and, possibly, how much to charge them as a result.

To do this, you’ll need the appropriate permissions for Subscription Contracts. Refer to our documentation on roles and permissions for more information.

Recording Usage

Your customer added a user to their license or downloaded a huge movie. Now what? Well, you’ll need to inform Crystallize of the usage that occurred. Use the Subscription API’s trackUsage mutation to create records of these events. You’ll need the IDs for the subscription contract and metered variable in question, which you can retrieve by querying subscription information on a product variant. The optional idempotencyKey can be used to give each transaction a unique ID, which can be used to ensure that duplicate events aren’t being recorded.

mutation {
  subscriptionContracts {
trackUsage(id: "subscription-contract-id", input: {
      meteredVariableId: "83e6a107654e328841fba1d4",
      quantity: 1
      idempotencyKey: "record123"
}) { id
      data {

Fetching Usage

You can use the following query to retrieve the usage for a specific contract/variable over a specified time period:

query {
  subscriptionContracts {
   get(id: "subscription-contract-id") {
      start: "2019-12-01T10:00:00Z"
end: "2020-12-01T10:00:00Z" ) {
      quantity }

How (or if) the customer is charged for this usage depends upon the metered variable tier types that have been defined for this subscription contract.

People showing thumbs up

Need further assistance?

Ask the Crystallize team or other enthusiasts in our slack community.

Join our slack community