Querying Subscription Information On Products

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.