Managing Subscription Contracts in the Crystallize App

Subscription contracts can be created programmatically with the Subscription API or with the Crystallize App. In order to create subscription contracts, you first must ensure the following:

• You have one or more customers defined within your tenant.
• You’ve created at least one subscription plan and have attached it to at least one product variant in your tenant’s catalogue. See our subscription plan documentation for more information.
• You have the requisite permissions for Customers, the Tree, and Subscription Contracts (read, create, etc). Refer to our documentation on roles and permissions for more information.

Within the App, click the Customers button on the left-hand panel. You can also bring up the command palette with [CTRL or ⌘] + K and type or select “Customers.” Select the customer you’d like to work with from the panel on the left, then click the action button (...) at the top of the screen and choose Add subscription contract. Using the catalogue pane on the left, browse to a product that has variants with subscription plan(s) attached. Once you’ve found one, drag and drop it into the Drag & drop subscription area of the screen. Finally, select the desired period from the drop-down menu and click the Select button beside the subscription you wish to add.

After a subscription has been selected, you can optionally adjust the following. Such adjustments will only affect this particular subscription contract and will not change the underlying subscription plan for this product variant:

• Price variant. Using the drop-down menu at the top right, choose one of the price variants already defined for this tenant.
• Subscription Product. The quantity of product variants for this contract. Adjusting this will affect the total price.
• Renewal. The date when the subscription contract comes up for renewal. By default, this is set to the current day/time plus the subscription period.
• Active until. The date when the subscription contract will expire if it’s not renewed. By default, this is set to the current day/time plus the subscription period.
• Unit Price. You can modify the price per product variant as desired. This will affect the total price.
• Metered Variables. For any metered variables associated with the subscription plan, you can adjust metered variable tier type, create or remove tiers, and set prices.

When finished, click the Create button in the top right.

Once created, the subscription contract will be visible on the Customers screen for the customer in question. Use the downward-pointing arrow on the left side of the subscription contract to access a detailed breakdown of metered variables (if applicable) and their current usage for the ongoing period. Predictive analytics provide estimates on future usage patterns and the associated total price. Leveraging data from past usage, this feature offers valuable foresight to empower informed decision-making.

If needed, you can also track the usage of metered variables programmatically.

To edit a subscription contract within the Crystallize App, first access the appropriate customer and scroll down to where their contracts are listed. Click on the subscription’s name to open it. From here, you can click the action button (...) in the top right and choose Edit contract. You can make changes to quantities, dates, prices, and tiers. Click either the Update button to retain your changes, or Cancel to revoke them.

You can also use the Subscription API to programmatically update subscription contracts and renew subscription contracts.

To delete a subscription contract within the Crystallize App, first access the appropriate customer and scroll down to where their contracts are listed. Click on the subscription’s name to open it. From here, you can click the action button (...) in the top right and choose Delete contract. This action is permanent and cannot be undone, so proceed carefully with deletion.

You can also use the Subscription API to programmatically cancel subscription contracts.

You can (optionally) set up webhooks to subscribe to subscription contract-related events. In Crystallize, events are fired whenever contracts are

• Created
• Updated
• Deleted
• Renewed
• Canceled

It’s good practice to create a webhook for the renewed event. See our Renewing Subscription Contracts documentation to learn more.

Additionally, you should create a webhook for the canceled event where you can send out a notification to the customer that the subscription has been canceled, and run other operations that you might need to do.

For more information, read about defining webhooks here.