Copy page

Concepts

Rate Cards

Rate cards define the pricing and entitlements for features within a plan. Each rate card connects a feature to a price and optionally sets usage limits or access controls. Rate cards are the building blocks that turn your product catalog into a monetizable offering.

What Rate Cards Define

A rate card consists of:

• Key and Name - Identifiers for the rate card (auto-filled from feature if linked)
• Feature - Optional link to a feature from your product catalog
• Price - How much to charge (see Pricing Models)
• Entitlement - Optional usage limits or access controls
• Billing Cadence - How often this rate card produces a charge — distinct from the plan's billing cadence, and constrained to align with it (see Billing Cadence below)

Rate Card Types

Flat Fee Rate Cards

Flat fee rate cards charge a fixed amount, either as a one-time charge or recurring fee. Use these for:

• Setup fees or onboarding charges
• Monthly or annual subscription fees
• Access fees for premium features

Code
{
  "type": "flat_fee",
  "key": "platform_fee",
  "name": "Platform Fee",
  "billingCadence": "P1M",
  "price": {
    "type": "flat",
    "amount": "99.00",
    "paymentTerm": "in_advance"
  }
}

When billingCadence is set (e.g., P1M), the flat fee recurs at that cadence — see Billing Cadence for the constraint relative to the plan's cadence. When billingCadence is null, the fee is charged once per subscription phase.

The paymentTerm field controls when the charge is collected:

• in_advance — Charged at the start of the billing period (most common for flat fees)
• in_arrears — Charged at the end of the billing period

Usage-Based Rate Cards

Usage-based rate cards charge based on metered consumption. These require a feature linked to a meter. Use these for:

• Pay-per-request API pricing
• Token-based AI model pricing
• Data transfer charges

Code
{
  "type": "usage_based",
  "key": "api_requests",
  "name": "API Calls",
  "featureKey": "api_requests",
  "billingCadence": "P1M",
  "price": {
    "type": "unit",
    "amount": "0.001"
  }
}

Usage-based rate cards support multiple pricing models. See Pricing Models for details on unit, tiered, package, and dynamic pricing.

Billing Cadence

A rate card's billingCadence controls how often this specific rate card produces a charge. It's distinct from the plan's billingCadence, which sets the overall invoice schedule for the subscription:

• For flat-fee rate cards, the cadence determines how often the flat fee recurs. Set it to null to charge once per subscription phase (a setup fee, onboarding charge, or other one-time payment).
• For usage-based rate cards, the cadence is required and determines the period over which metered usage is aggregated and emitted as an invoice line.

Alignment with the plan

The rate card's cadence must align with the plan's billingCadence. Two cadences align when:

• They are identical (e.g., plan P1M and rate card P1M), or
• The shorter one divides the longer one without remainder (e.g., plan P1M with a rate card at P3M, or plan P1Y with a rate card at P1M).

Plans accept these billingCadence values: PT1H, P1D, P1W, P2W, P4W, P1M, P3M, P6M, P12M, P1Y. A rate card with a cadence that doesn't align (for example, P2M on a P3M plan, where neither divides the other) is rejected at plan creation.

This rule exists for invoice-generation correctness: it guarantees that every rate-card cycle ends on a plan-invoice boundary, so a single charge from this rate card lands on exactly one customer invoice rather than straddling two.

Rate Cards With Features

When a rate card is linked to a feature via featureKey:

• The rate card's key and name are pre-filled from the feature
• You can define entitlements to control access or set usage limits
• For metered features, the rate card can track and bill based on usage

Entitlement Types

Entitlements define what customers get access to:

Type	Description
boolean	Simple on/off access to a feature
static	Access with custom configuration (JSON)
metered	Access with usage tracking and optional limits

Metered Entitlements

Metered entitlements are the most common for usage-based pricing. They can include:

• Usage limits - Cap how much a customer can use
• Soft limits - Allow overage beyond the limit (with overage charges)
• Initial grants - Starting balance that resets each period
• Overage preservation - Whether overage carries over after reset

Code
{
  "type": "usage_based",
  "key": "api_requests",
  "name": "API Calls",
  "featureKey": "api_requests",
  "billingCadence": "P1M",
  "price": {
    "type": "unit",
    "amount": "0.001"
  },
  "entitlementTemplate": {
    "type": "metered",
    "issueAfterReset": 10000,
    "isSoftLimit": false,
    "preserveOverageAtReset": false,
    "usagePeriod": "P1M"
  }
}

This example grants 10,000 API calls per billing period with a hard limit.

Property	Description
issueAfterReset	Number of units granted at the start of each usage period
isSoftLimit	If true, requests continue after quota (overage billing applies)
preserveOverageAtReset	If true, overage carries over to the next period
usagePeriod	ISO 8601 duration for the usage reset period (e.g., P1M)

Rate Cards Without Features

Rate cards without features can only use flat fee pricing. The key and name must be manually specified and will appear on invoices. These are useful for:

• Platform fees unrelated to specific features
• Service charges
• Custom line items

Free Items

You can offer free items in three ways:

1. Omit the price - No price means free, and no payment method is required
2. Set price to $0 - Explicit free, but payment method may still be required
3. Apply 100% discount - Shows original value with discount applied

Adding Rate Cards to Plans

Rate cards are added to plan phases. See Plans for a complete example of creating a plan with trial and default phases using rate cards.