Crystallize logo

Subscription contracts

A subscription contract is an agreement that defines future order(s) at an agreed upon price. Subscription contracts trigger events that you can use to create orders. Typical examples are on contract create and renew.

Creating a subscription contract

A subscription contract defines the agreement between you and a customer. It is created when a customer subscribes to a product and includes all the details about the subscription period, pricing, renewal, and any metered variables. Contracts are the source of truth for generating recurring orders and handling renewals.

Creating a Subscription Contract

You can create a contract directly in the Crystallize App:

  1. Navigate to a customer (individual or organization).
  2. Click Add subscription contract.
  3. On the contract creation screen:
    • The subscription product and plan are pre-filled based on the selected subscription offering.
    • Periods (initial and recurring) are automatically applied if defined in the offering.
    • Any metered variables are also included.
    • Included products – Add additional items bundled into the subscription.
      Example: A hardware device included in the initial period alongside a SaaS subscription.

Creating subscription contract

Bundled Subscriptions

Contracts can include multiple products, allowing you to create subscription bundles. 

This is useful when combining:

  • Hardware + service (e.g. a smart device with a service plan).
  • Multiple software features in a single subscription.
  • Physical goods bundled with a recurring digital subscription.

API Integration

Subscription contracts can also be created and managed programmatically via the Shop API and Core API. For external facing use cases like the storefront the Shop API should be used for performance reasons.


This allows you to:

  • Automate contract creation during checkout.
  • Sync subscription data with external systems.
  • Handle advanced scenarios like custom billing dates or enterprise agreements.

Key Takeaways

  • Contracts connect customers to subscription offerings.
  • They define start dates, renewal rules, pricing, and included products.
  • Recurring orders are generated from contracts.
  • You can create and edit contracts in the Crystallize App or via the API.

Keep exploring

Managing Customer and Customer Groups

Customers are the entities (individuals or organizations) that transact with your store — via one-time orders, subscriptions, or both. They serve as a central anchor that links orders and subscription contracts to real-world identities. You can store as little or as much information as you like, depending on your use cases.

There are three main customer entity types:

  • Individual - A single person (with name, email, address).
  • Organization - A company or legal entity (can include multiple users or contacts).
  • Group - A container or folder for organizing customers or sub-groups (useful for markets, project teams, internal segmentation).

You can nest Groups, Organizations, and Individuals in a hierarchical tree (up to 5 levels deep). This is especially useful in B2B contexts where companies have subsidiaries or multiple departments.