Subscription Overrides

A customer negotiated 50 seats when their plan gives 10. You do not want a new plan for one account. An override changes one entitlement value on one subscription, and leaves the plan alone.

What can be overridden

Overrides work on entitlements, not on prices.

Metric type	Can be overridden
boolean	Yes — turn a feature on or off for this customer.
gauge	Yes — raise or lower a count, like seats.
static	Yes — change a fixed configured value.
metered	No. The API rejects it with 400.

Metered metrics are priced by metering rules and paid for with credits. If you want one customer to pay a different rate, that is a pricing question, not an entitlement override. Grant them credits, or put them on a different variant.

Creating one

curl -X POST https://api.quotastack.io/v1/subscriptions/{subscription_id}/overrides \
  -H "X-API-Key: qs_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "billable_metric_key": "seats",
    "value": { "limit": 50 },
    "expires_at": null,
    "reason": "Negotiated at renewal, approved by sales"
  }'

Field	Required	Meaning
billable_metric_key	Yes	Which entitlement to override.
value	Yes	The new value. Its shape must match the metric’s type.
expires_at	No	When the override stops. null means it never stops.
reason	No	Why. Write something — the next person to read this will thank you.

The value shape follows the metric type, exactly as it does on the plan variant. A gauge takes a limit, a boolean takes an enabled flag. See Plan-Variant Entitlements for the shapes.

How it interacts with the plan

The override wins for that one metric on that one subscription. Everything else on the variant is untouched — other entitlements, credit grants, billing cycle, all unchanged.

When the override expires, the variant’s own value applies again. Nothing needs to be cleaned up for that to happen.

Replacing an override

Create a second override for the same subscription and the same metric, and QuotaStack replaces the expired one rather than stacking a duplicate. You do not need to delete the old one first.

Reading and removing

List everything set on a subscription:

curl https://api.quotastack.io/v1/subscriptions/{subscription_id}/overrides \
  -H "X-API-Key: qs_live_..."

Read or delete a single one by its metric key:

curl -X DELETE https://api.quotastack.io/v1/subscriptions/{subscription_id}/overrides/seats \
  -H "X-API-Key: qs_live_..."

Deleting an override returns the customer to the plan’s value straight away.

Environments

An override does not carry an environment of its own. It does not need one: it belongs to a subscription, and subscriptions are separated by environment. An override on a sandbox subscription affects that sandbox subscription and nothing else.

This is worth knowing because the catalog behaves the opposite way — see Environments & the Shared Catalog.

Keep them rare

An override is a promise you made to one customer, recorded in one row. That is fine for a handful of accounts. When you find yourself writing the same override for the tenth customer, that is a plan variant asking to exist.

Every override is written to the audit log, so you can always find out who has one and why.