Entity relationship diagram
The following diagram shows the key entities in Stigg and how they relate to each other:How entities relate
Stigg’s data model can be understood in two parts: how you model your pricing (product catalog) and how your customers interact with it (customer lifecycle).Product catalog
You start by defining Features — the individual capabilities your product offers (e.g., “API calls”, “Seats”, “Premium support”). Features define what can be controlled. For metered features, a Meter defines how usage data is aggregated (e.g., sum of API calls, count of active seats). Features are then packaged into Plans and Add-ons through Entitlements. An entitlement is a combination of a feature and its configuration — it defines how much of that feature a plan grants. For example, the feature “API calls” might have an entitlement of “10,000 per month” in a Pro plan, and “unlimited” in an Enterprise plan. Both Plans and Add-ons belong to a Product. Plans are the primary subscription offering, while Add-ons extend plans with additional capabilities. Each plan and add-on has one or more Prices that define the billing model (flat fee, per-unit, or usage-based), billing period, and currency.Customers and subscriptions
A Customer subscribes to a Plan, creating a Subscription. The subscription can also include one or more Add-ons. The customer’s effective entitlements are computed from all of these sources combined. For products that support multi-tenancy, a Customer can have multiple Customer Resources (e.g., workspaces, projects, or organizations). Each resource can hold its own subscriptions and entitlements independently. Additionally, Promotional entitlements (overrides) can be granted directly to a customer — independent of their subscription. This is useful for exceptions: e.g., temporarily increasing a customer’s API call limit after they hit a usage spike by mistake.Usage and billing
For metered features, Usage measurements track the customer’s consumption against their entitlement limits. Coupons can be applied to subscriptions or customers for billing discounts.Credits
For prepaid and credit-based pricing models, customers can have Credit pools — one per Credit currency. Each pool is funded by Credit grants (allocations with their own amounts, expiration dates, and priorities). Consumption mappings define how metered feature usage converts into credit deductions (e.g., “1 API call = 2 AI Tokens”). As usage is reported, Stigg deducts credits from the customer’s pool in real time.How entitlements are calculated
A customer’s effective entitlements come from multiple sources:- Plan entitlements — from the plan in their active subscription
- Add-on entitlements — from any add-ons included in their subscription (additive)
- Promotional entitlements — customer-specific overrides granted directly
- Trial subscriptions — entitlements from overlapping trial periods
Products
A product is the foundational object that defines a product or product-line you offer to your customers. It acts as the entry point for modeling pricing, managing plans, and defining the customer lifecycle. Products control how many active subscriptions a customer can hold—either a single subscription or multiple parallel ones—and determine the default behaviors that govern how customers begin, change, or end their subscription journey. Each product also serves as the context for displaying pricing to users and for enforcing subscription logic through SDKs and APIs. Once a product is created, it becomes the anchor for configuring plans, entitlements, usage charges, and trial behavior—all of which collectively define how your product is packaged and monetized.Plans
Plans define how a product is packaged, priced, and made available to customers over a specific billing interval—such as monthly or annually. Each plan encapsulates a combination of features, pricing logic, and optional free trial behavior. These plans act as subscription templates that customers can activate either through self-serve flows or custom provisioning logic. Plans are always linked to a product and serve as the foundation for your monetization strategy. They determine what customers can access, how they’re billed, and how they interact with the product during onboarding, upgrades, downgrades, and cancellations. Stigg’s versioning and visibility tools allow product and growth teams to make changes to plans—such as modifying prices, updating entitlements, or rolling out new tiers—without engineering support. Stigg supports three types of plans, each suited to a different pricing and delivery model:- Free plans are designed for freemium strategies, offering limited functionality at no cost. They don’t require payment information and often include usage limits to drive upgrades.
- Paid plans are fully monetized offerings with fixed or usage-based pricing. These plans support billing periods, charges, minimum spend, and free trial options, and can be connected to external billing providers like Stripe.
- Custom plans are flexible templates used for sales-led engagements. They support variable pricing and feature configurations negotiated on a per-customer basis and are typically provisioned manually or via API.
Add-ons
Add-ons allow you to offer separately billable functionality that extends the capabilities of existing paid or custom plans. Unlike plans, add-ons are designed to be modular and composable—customers can purchase them individually or in multiples to enhance their core subscription. Each add-on grants specific functionality defined through entitlements, such as additional usage limits, advanced features, or expanded quotas. These entitlements are additive by default: the total value a customer receives for a feature is the sum of entitlements from both the base plan and any active add-ons. In multi-instance configurations, the entitlements are multiplied by the number of add-on units purchased. Add-ons are fully tied to the lifecycle of the plan they extend. When a customer’s subscription to a plan ends, any associated add-ons are deactivated as well. Add-ons can also define their own pricing, billing periods, visibility, and compatibility rules—providing teams with the flexibility to monetize additional value independently of core plans. Stigg supports two types of add-ons:- Paid add-ons: Designed for self-serve scenarios, paid add-ons include a recurring charge and can be published to appear in customer-facing pricing tables. They support multiple billing intervals and currency localization.
- Custom add-ons: Best suited for negotiated or enterprise deals, custom add-ons allow sales teams to define pricing and entitlements on a per-customer basis. These add-ons must be paired with a custom plan and are excluded from automated billing system integrations.
Prices
Prices define the billing configuration for plans and add-ons. Each price specifies the billing model, billing period, and amount. A single plan or add-on can have multiple prices — for example, a monthly and an annual option, or prices in different currencies. Stigg supports the following billing models:- Flat fee: A fixed recurring charge per billing period (e.g., $49/month).
- Per-unit: A charge multiplied by the number of units the customer selects (e.g., $10/seat/month).
- Usage-based: A charge calculated from the customer’s actual consumption of a metered feature during the billing period.
Features
Features define the individual capabilities of your product that can be controlled and monetized. A feature represents what can be gated — for example, “API calls”, “Team members”, or “Premium support”. Features on their own don’t grant access to anything. They become meaningful when assigned to plans or add-ons as entitlements, which configure how much of the feature is available. Stigg supports the following feature types:- Boolean features: Grant or deny access to a capability using a simple on/off switch. Ideal for enabling discrete features like “Premium Support” or “Access to API.”
- Configuration features: Assign a numeric value that controls a feature’s behavior—for example, “Number of team members” or “Max projects.”
- Metered features: Track usage over time, with optional limits. These are commonly used for usage-based pricing models, such as “API calls per month” or “Messages sent.” Stigg can optionally reset the measured usage every predefined period (monthly, weekly, daily, or hourly).
- Enum features: A specialized form of configuration feature that allows you to assign one or more values from a predefined list—useful for options like “Supported countries,” “Available templates,” or “Support tier.”
Meters
A meter defines how raw usage data is aggregated for a metered feature. It specifies the aggregation function (such as sum, count, or average), the data field to aggregate, and optional filters. For example, a meter for “API calls” might use acount aggregation on all events matching the api.request event name. Meters are what connect raw usage events to the feature’s usage value that is checked against entitlement limits.
Entitlements
Entitlements are the bridge between features and plans. An entitlement is the combination of a feature and its configuration — it defines what a customer is entitled to use, and to what extent.Feature vs. Entitlement: A Feature defines what can be controlled (e.g., “API calls”). An Entitlement defines how much of that feature a specific plan or customer gets (e.g., “10,000 API calls per month”). Think of features as the vocabulary and entitlements as the sentences — features are reusable building blocks, while entitlements express specific access levels.
- Package entitlements — assigned to a plan or add-on. Every customer who subscribes to that plan gets these entitlements. For example, the Pro plan might include an entitlement of “10,000 API calls per month” for the “API calls” feature.
- Promotional entitlements (overrides) — granted directly to a specific customer, independent of their plan. These are useful for exceptions, such as temporarily increasing a limit for a customer or granting access to a feature outside of their current plan. Promotional entitlements can have a defined time period (e.g., one month, one year) or last for the customer’s lifetime.
Promotional entitlements
Promotional entitlements allow you to override a customer’s standard plan entitlements on a per-customer basis. They are one of the most powerful capabilities in Stigg, enabling you to handle the exceptions that inevitably arise in real-world customer relationships. Common use cases include:- Temporary limit increases — A customer hits their API limit due to a coding error. You grant a promotional entitlement with a higher limit until the end of the billing period, keeping them unblocked.
- Feature trials — Give a specific customer access to a premium feature for a limited period to drive an upgrade.
- Enterprise accommodations — Grant custom limits or capabilities as part of a negotiated agreement without creating a one-off plan.
- Goodwill gestures — Temporarily extend access for a customer who experienced an issue.
Coupons
Coupons in Stigg are discount instruments that can be applied to customers or specific subscriptions to reduce their billing amount. Coupons support either percentage-based or fixed-amount discounts and can be configured with a limited or unlimited duration. When applied to a customer, the coupon affects all active subscriptions associated with that customer. When applied to a specific subscription, only that subscription receives the discount. Coupons can be managed centrally within the Product Catalog and support metadata for integration with custom business logic via Stigg’s SDKs, API, and webhooks. When integrated with billing providers (e.g., Stripe), coupon names also appear on customer invoices.Customers
In Stigg, a Customer represents an individual or organization that holds one or more subscriptions and interacts with your product. Each customer has a unique ID (immutable), and optionally a name and email address used for display and billing purposes.Customer resources
A customer resource represents a distinct entity within a customer’s account — such as a workspace, project, or organization. Resources enable multi-tenancy: each resource can hold its own subscriptions, entitlements, and usage measurements independently of the parent customer and other resources. This is useful when your customers manage multiple independent units that each need their own plan. For example, a customer might have three workspaces, each subscribed to a different plan with its own usage limits.Subscriptions
A subscription defines the specific set of functionality a customer has access to, under what terms, for how long, and at what cost. It links a customer to a plan and optional add-ons, and determines the customer’s entitlements, usage limits, and billing behavior. Subscriptions may include trials, discounts, or usage-based charges, and support real-time updates such as upgrades, downgrades, and scheduled changes. Each subscription reflects the current state of the customer’s relationship with your product and is central to how access and pricing are managed in Stigg.Usage measurements
Usage measurements track a customer’s consumption of metered features as part of their subscription. This data is used to enforce entitlement limits and, when integrated with a billing provider, to calculate usage-based charges. Stigg supports two approaches for getting usage data:- Calculated usage — Your application reports the current usage value directly (e.g., “this customer currently has 5 seats”).
- Raw usage events — Your application sends individual usage events (e.g., “1 API call made”), and Stigg aggregates them.
Environments
An environment represents an isolated workspace within an account, used to manage and test pricing, packaging, and customer access in different stages of your development lifecycle. Each environment—such as development, staging, or production—maintains separate configurations, data, and API keys. Production environments are used for real customer interactions and are subject to usage limits and SLAs, while non-production environments serve as sandboxes for experimentation without impacting live data. This separation ensures safe iteration and controlled rollout of pricing changes across your software delivery pipeline.Credits
Credits in Stigg are units of value in a custom currency that you grant to customers and deduct as they use metered features. They make usage-based pricing simple and transparent. Each customer has a credit pool per currency with a ledger tracking all actions: grants, deductions, expirations, and adjustments. Credits can be used for prepaid packs, recurring allowances in subscriptions, promotional offers, or hybrid pricing models.Credit currency
Credit currencies define the units of value tracked in credit pools. Each credit currency is a separate, non-interchangeable balance used for credit-based pricing. Customers may hold multiple credit pools—one per currency—and usage tied to one currency cannot consume another.Credit pools
Credit pools represent a customer’s live balance of a specific credit currency. Each pool is funded by credit blocks (grants or allocations) and reduced in real time as usage is reported. Every change—grants, deductions, expirations, or adjustments—is logged in an append-only ledger. A pool may contain multiple blocks with their own amounts, expiry rules, categories, and priorities, and reflects the customer’s available credits at any point in time.Consumption mapping
Consumption mapping defines how metered usage converts into credit deductions. For each metered feature, you specify the conversion rate—such as1 email = 1 AI Token or 1,000 tokens = 1 credit. When usage events are ingested, Stigg applies these mappings in real time to deduct the appropriate amount from the customer’s credit pool. Each mapping is tied to a specific credit currency and supports event-based meters.