Querying Subscription Information On Products
When creating a subscription contract for a customer, you first need to know what (if any) subscription plans are associated with the desired product variant. You’ll use the Subscription API to query the product catalogue for this information.
To do this, you’ll need the appropriate permissions for Subscription Plans. Refer to our documentation on roles and permissions for more information.
Here’s a sample query that retrieves subscription information on all product variants in a specified catalogue path:
query PRODUCT_WITH_SUBSCRIPTION($path: String!, $language: String) {
catalogue(path: $path, language: $language) {
... on Product {
name
variants {
subscriptionPlans {
identifier
name
periods {
id
name
initial { ...pricing }
recurring { ...pricing }
}
}
}
}
}
}
fragment pricing on ProductVariantSubscriptionPlanPricing {
period
unit
priceVariants { ...priceVariant }
meteredVariables {
name
identifier
tierType
tiers {
threshold
priceVariants { ...priceVariant }
}
}
}
fragment priceVariant on ProductPriceVariant {
identifier
price
currency
}You can try this query out for yourself on our public subscriptions demo tenant: https://api.crystallize.com/subscriptions-demo/catalogue To get it working, you’ll first need to copy/paste the following variable into the Query Variables window in the bottom left:
{
"path": "/mobile-subscription-metered"
}Once you do, you should get a response like this:
{
"data": {
"catalogue": {
"name": "Mobile subscription - metered",
"variants": [
{
"subscriptionPlans": [
{
"identifier": "mobile-subscription",
"name": "Mobile subscription",
"periods": [
{
"id": "61e01cd0ec1318c567929dc2",
"name": "Monthly",
"initial": null,
"recurring": {
"period": 1,
"unit": "month",
"priceVariants": [
{
"identifier": "default",
"price": 5,
"currency": "eur"
}
],
"meteredVariables": [
{
"name": "SMS",
"identifier": "sms",
"tierType": "graduated",
"tiers": [
{
"threshold": 0,
"priceVariants": [
{
"identifier": "default",
"price": 0,
"currency": "eur"
}
]
},
{
"threshold": 100,
"priceVariants": [
{
"identifier": "default",
"price": 0.1,
"currency": "eur"
}
]
}
]
},
{
"name": "Phone call minutes",
"identifier": "phone-call-minutes",
"tierType": "graduated",
"tiers": [
{
"threshold": 0,
"priceVariants": [
{
"identifier": "default",
"price": 0,
"currency": "eur"
}
]
},
{
"threshold": 120,
"priceVariants": [
{
"identifier": "default",
"price": 0.1,
"currency": "eur"
}
]
}
]
},
{
"name": "Bandwidth",
"identifier": "bandwidth",
"tierType": "graduated",
"tiers": [
{
"threshold": 0,
"priceVariants": [
{
"identifier": "default",
"price": 0,
"currency": "eur"
}
]
},
{
"threshold": 2,
"priceVariants": [
{
"identifier": "default",
"price": 1,
"currency": "eur"
}
]
}
]
}
]
}
}
]
}
]
}
]
}
}
}This is a quite large response, since this product variant’s subscription plan contains metered variables with multiple tiers. Let’s look closer at the subscription plan attributes:
"subscriptionPlans": [
{
"identifier": "mobile-subscription",
"name": "Mobile subscription",
"periods": [
{
"id": "61e01cd0ec1318c567929dc2",
"name": "Monthly",
"initial": null,
"recurring": {
"period": 1,
"unit": "month",
"priceVariants": [
{
"identifier": "default",
"price": 5,
"currency": "eur"
}
]
If a product variant has any subscription plans, they would show up as subscriptionPlans. Each plan needs to define subscription periods, and for this plan there’s a monthly period, helpfully named “Monthly.” You can see further within the recurring object that the recurring.unit is “month” and the recurring.period is 1. This subscription has a base price of 5 euros per subscription period, or €5 per month.
Now let’s look at the metered variables, using phone call minutes as the example here:
{
"name": "Phone call minutes",
"identifier": "phone-call-minutes",
"tierType": "graduated",
"tiers": [
{
"threshold": 0,
"priceVariants": [
{
"identifier": "default",
"price": 0,
"currency": "eur"
}
]
},
{
"threshold": 120,
"priceVariants": [
{
"identifier": "default",
"price": 0.1,
"currency": "eur"
}
]
}
]
},Each metered variable has tiers and metered tier types that determine how pricing will work. In this example using graduated pricing, calling is free for the first 120 minutes (since the price is 0) of the period (1 month), then the customer will be charged €0.10 for each additional minute of phone call time.
Now that we know how to retrieve subscription data, we’re ready to create subscription contracts.
