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.
You can manage subscription usage manually within the Crystallize App or programmatically, as described below. 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
type
createdAt
data {
meteredVariableId
quantity
idempotencyKey
}
}
}
}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") {
usage(
start: "2019-12-01T10:00:00Z"
end: "2020-12-01T10:00:00Z" ) {
meteredVariableId
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.
