---
title: Subscription Overrides
description: Give one customer a different entitlement value from the rest of their plan, without building a plan for one person.
order: 15
---

# 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.

> **Mental Model:** An override is **a sticky note on one customer's contract**. The plan still says 10 seats; the note says 50 for this account only. Everything else on the contract is unchanged, and when the note comes off, the plan's number applies again.

## Quick Take

- Overrides change **entitlements**, not prices
- Works on `boolean`, `gauge`, and `static` metrics
- **Metered metrics are rejected with `400`** — pricing is not an entitlement
- `expires_at: null` means permanent; on expiry the plan value applies again
- Creating a second override for the same metric replaces the expired one

## Diagram

An entitlement value resolves from the plan variant unless the subscription has an override for that metric, in which case the override wins until it expires.

```mermaid
flowchart LR
    Q[Entitlement check] --> O{Override on this<br/>subscription + metric?}
    O -->|yes, not expired| V1[Use the override value]
    O -->|no| V2[Use the variant's value]
```

## 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

```bash
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](/docs/concepts/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:

```bash
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:

```bash
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](/docs/concepts/environments).

## 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](/docs/concepts/audit-log), so you can always find out who has one and why.

## Common Mistakes

**✗ Don't try to override a metered metric**

The API returns 400. Metered usage is priced by metering rules and paid in credits — grant credits or change the variant instead.

**✗ Don't delete an old override before writing the new one**

Creating one for the same subscription and metric replaces the expired one for you.

**✗ Don't use overrides as a substitute for a plan**

The tenth customer with the same override is a variant asking to exist. Overrides are for exceptions.

## Related

- [Plans & Variants](/docs/concepts/plans-and-variants) — Where the value being overridden comes from.
- [Plan-Variant Entitlements](/docs/concepts/plan-variant-entitlements) — The typed value shapes an override must match.
- [Entitlements](/docs/concepts/entitlements) — How a check resolves at request time.
- [Audit Log](/docs/concepts/audit-log) — Every override is recorded with who set it and why.