Overrides & Enterprise Deals

Safely customize features and pricing per customer without breaking your plan model

What this is

Overrides let you customize a single customer’s subscription without changing the underlying plan. Enterprise deals often need bespoke feature values or tailored pricing. Use overrides to change the customer experience safely while keeping plans clean and reusable.

When to use it

Temporary boosts or exceptions (support cases, trials beyond standard)
Enterprise deals with bespoke limits or add‑ons
Legacy pricing migrations that shouldn’t affect the base plan
Correcting mistakes without creating a new plan version

Quick examples

Subscription feature override (numeric)

{
  "featureSlug": "api-calls",
  "value": 50000,
  "reason": "enterprise-deal-ACME",
  "effectiveFrom": "2025-09-01T00:00:00Z",
  "effectiveUntil": null
}

Ephemeral price tweak (one cycle)

{
  "priceId": "price_monthly_base",
  "components": [
    {
      "type": "fixed",
      "label": "Enterprise concession",
      "amount_cents": 2500,
      "recurrence_rule": "RRULE:FREQ=MONTHLY;INTERVAL=1"
    }
  ],
  "expiresAfterBillingCycles": 1
}

Decision guide: new plan version vs override

Choose an override when a change is bespoke and not meant to be reused
Create a new plan version when you’ll reuse the change across many customers
For price changes that will become the new standard, version the plan and map prices

Safe migration notes (high‑level)

Prefer append‑only changes; avoid destructive edits to historical data
Schedule migrations at next_billing_cycle when price IDs change
Maintain explicit price mappings between versions to preserve invoices and proration behavior

UI vs API

UI (light edits)
- Adjust subscription feature values for a single customer
- Apply small, time‑boxed concessions
API (full control)
- Create and revoke overrides programmatically at subscription or customer level
- Generate ephemeral prices, map to plan versions, and schedule migrations
- Bulk operations for migrations and legacy contract management

Common pitfalls

Using overrides for reusable changes → create a new plan version instead
Forgetting expiry on temporary concessions → lingering discounts
Overriding numeric features without aligning metrics/credits → entitlement checks don’t reflect intent
Changing price structure without explicit mappings → migration surprises at renewal
Mixing customer‑level and subscription‑level overrides unintentionally