Subscriptions (API) Overview

Sellers might offer different subscription models, such as:

• 100GB for $70 a month
• 100GB for $50 a month if you are a students
• 150GB free for 3 months and then $95 a month
• 150Gb for $900 per year

You can already see the confusion, right? The sheer number of possibilities makes it so. Sellers think of subscriptions as products in their catalog, while buyers see them as recurring services that track usage and charges periodically. It is a balancing act between affordability and profitability.

Everything starts with a Subscription Plan, the simplest entity where you set up different period possibilities. Each Period can have an optional initial phase and a required recurring phase. Periods can be defined as days, weeks, months, or years.

Besides the periods, you can add Metered Variables, enabling you to track usage.

To achieve a monthly and yearly subscription system, you can choose one of these approaches:

• One subscription plan has two periods: monthly and yearly.
• Two Subscription plans with one period each: monthly and yearly.

The choice depends on whether you want to share the metered variable across different plans. In essence, Crystallize allows you to build your subscription model to match your business needs.

Once you have a subscription plan, you can create Product Variants associated with one or many subscription plans. For instance, suppose you are a renowned electric car brand offering a self-driving feature. You could sell this feature for a one-time fee or offer it as a subscription service.

You can set this up in Crystallize by creating a subscription plan. Then, you create a new product variant (SKU) where you can set the price for the one-time fee and establish a base price for the subscription option.

The base price of a subscription plan is nice, but if you have a scenario where you want usage-based pricing, using Metering variables will let you define the Pricing Tiers of different variables. Like for example, a base price of $100 plus $5 for every 1GB of bandwidth used.

Metered variables allow you to set pricing tiers at the product variant level with two main methods:

• Volume-Based: A single price for all units within a tier, reducing the cost per unit only when the volume crosses into the next tier.
• Graduated: Different prices for portions of the total volume, pricing units incrementally as they fall into different tiers.

Let’s explain this with an example. You have three tiers: 

• Tier 1: 1-10 units at $10 each
• Tier 2: 11-20 units at $8 each
• Tier 3: 21+ units at $6 each

A volume-based variable would kick in when the condition is that if you buy 15 units, you pay $8 per unit, totaling $120. Conversely, a graduated variable means that if you buy 15 units, you pay 10 units at $10 each ($100) plus 5 units at $8 each ($40), totaling $140.

The above examples can be integrated consistently in Crystallize, and for each tier, you can manage the price in different currencies and/or markets.

Now, let’s discuss what happens after a subscription plan on an SKU is purchased. This is represented by a Subscription Contract, which acts as a real-life contract that locks in the pricing and content of the subscription at the time of purchase. It’s the glue between the Catalog and the customer. 

Without a subscription contract, Crystallize is just a product catalog with list prices. The contract holds the prices for a specific customer on a specific subscription plan. You can create a subscription contract with customized pricing, and catalog pricing serves as a rate card.

On top of freezing the Prices for the recurring period and the optional initial period, a Subscription Contract includes the following important properties:

• Signed Date. The contract start date.
• Renewal Date. The anniversary date is to renew the contract for one period.
• Active Until Date. This contract is active until then. Indeed, you could have paid up to the 28th and canceled on the 15th.

Do you need to manage usage storage on your own? Not with Crystallize. If the subscription plan attached to the subscription contract has metered variables, Crystallize allows you to track the usage of metered variables directly in the contract. You can access usage data to compute the total amount a customer must pay upon renewal. The UI also provides current usage visibility.

In simple terms, the contract serves as the pricing reference for a customer to create a future order based on an agreed-upon price.

Payments in Crystallize are handled separately from the subscription itself. Postpaid or prepaid subscriptions can be managed using webhooks and orders.

A typical flow for postpaid subscriptions with metering is:

• Renewal: Crystallize fires an event that triggers a webhook.
• Webhook: The implementation receives the subscription contract and fetches usage data. After calculating the total price, an order is created in Crystallize.
• Order Creation: Another event is fired, triggering a webhook to charge the customer. Payment information can be set on the subscription contract or the customer record.
• Error Management: Use order pipelines to handle cancellations, add-ons, charge retries, etc.

The Subscription API handles everything related to subscription plans and the subscription contracts associating subscription-based products with customers.