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, either by clicking on their name within the left-hand panel or by clicking on their identifier within the spreadsheet view. With the customer record open, click the action button (...) at the top of the screen and choose Add subscription contract. If the customer currently has no orders or contracts, there will also be a Subscription contract button at the top of their record that you can click to get started.

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.

Now that you have a subscription contract in place, you must create an order for it. You can either do this with the Order API or within the Crystallize App. In the App, first access the appropriate customer, then click on the subscription’s name to open it. From here, you can see the full details of the contract. Click the action button (...) in the top right and choose Create Order.

On the order creation page, the contract will be listed as an order item. You’re free to add additional items and update quantities and prices as desired. You can also enter any necessary metadata as key-value pairs. Once finished, click the Create Order button in the top right. The order will be added to the Orders screen and any fulfilment pipeline(s) you may have set up for new orders. Any webhooks you’ve previously set up for these events will fire.

You can use the Subscription API or Crystallize App to edit subscription contracts. Within the App, first access the appropriate customer, then click on the subscription’s name to open it. From here, you can see the full details of the contract.

If you wish to manually add usage, click the plus sign button (+) beside any metered variable. Enter the desired quantity, then click Add. 

To modify the contract itself, 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 use the Subscription API or Crystallize App to cancel subscription contracts. Within the 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 (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.