Source: https://www.revvly.ai/docs/guides/custom-agreements

Guide

# Negotiate a *private* deal.

A Custom Pricing Agreement overrides one Variable Component for one customer. It beats every Variable Component Price scope, takes effect at the customer’s next renewal, and is fully audited via the Lifecycle Event log.

## When to write one

Reach for a Custom Pricing Agreement when:

- You’ve negotiated bespoke unit pricing with a single customer.
- You need to override more than one axis at once (e.g. `PRICE` + `CURRENCY`).
- You want a different pricing *model* for one customer — say, switching them from flat to commission.
- You want an audited, sweepable, time-bounded override rather than a quiet edit at the Subscription price scope.

For one-off rate tweaks limited to a single subscription, a Subscription-scope[Variable Component Price](https://www.revvly.ai/docs/concepts/variableComponentPrice) may be enough. The Agreement is the right tool when more than one axis moves, or when finance needs the change recorded as an explicit deal.

## Override axes

You opt into specific axes via the `overrideScope` array. Only the axes you opt into are required — everything else falls through to the base component.

- **Price**: Override any monetary or quantity field — flat unit price, the tier ladder, stairstep fees, the overage price, included units, or committed quantity. One axis covers the whole price shape.

- **Pricing model**: Change the pricing model entirely for one customer (e.g. flat rate → commission).

- **Proration**: Swap the proration calculation — Full month / Daily / None — for this customer.

- **Billing timing**: Switch Advance ↔ Arrears for this customer only.

- **Currency**: Bill this customer in a different currency than the component default.

## Lifecycle

Draft → Published → Effective → (Revoked or Expired).

1. 1DraftYou author the agreement, pick the override axes you care about, and fill in the new values. Drafts are editable indefinitely and never affect billing.
2. 2PublishedPublishing freezes the agreement and signals intent. From this point it is immutable — to change a value you must Revoke and re-author. Publishing also slots the agreement into the resolution chain.
3. 3EffectiveA Published agreement takes effect at the customer's next renewal on or after effectiveFrom. The renewal invoice uses the overridden numbers; the underlying components on other customers are unaffected.
4. 4Revoked / expiredRevoke at any time to remove the override at the next renewal. If expiresAt is set, a background sweep moves the agreement to Archived after that date and the customer renews back onto the base component pricing.

Life of an agreement

1. DraftEditable, never affects billing.
2. PublishedFrozen and added to the resolution chain.
3. EffectiveApplies at the next renewal on or after effectiveFrom.
4. RevokedOverride removed at the next renewal.orExpiredArchived after expiresAt; base pricing returns.

Only a Published agreement can bill; changing a value means revoking and re-authoring.

## How it wins

Custom Pricing Agreements override everything below them. The full resolution order at billing time, from highest to lowest priority, is:

```
Custom Pricing Agreement (Published, effective)
        ↓
Subscription-scope Variable Component Price
        ↓
Bundle-scope Variable Component Price
        ↓
Module-scope Variable Component Price
        ↓
Global default Variable Component Price
```

The agreement is matched on **(customer, component)** — not on the subscription. If a customer holds multiple subscriptions and they all include the same Variable Component, a single agreement applies to all of them at their respective next renewals.

## Audit trail

Every publish, revoke, and expiry sweep is captured by the[Lifecycle Event log](https://www.revvly.ai/docs/concepts/lifecycleEvent). When the agreement takes effect at renewal, the renewal’s RENEWED event already carries the new MRR delta — there is no separate “agreement applied” event, because the agreement is just one input to the standard renewal pricing.

## Common patterns

- **Discount one component**: Override `PRICE` for the seats component (its unit price), leave everything else inherited.

- **Enterprise rate card**: Override `PRICE` with the customer-specific tier ladder agreed in the contract.

- **Local-currency billing**: Override `CURRENCY` + `PRICE` together so the customer is billed in EUR at a fixed rate.

- **Take-rate deal**: Override `MODEL` to switch a flat-rate component to a commission component for one marketplace customer.

## Next up

- [Pricing models reference ›](https://www.revvly.ai/docs/guides/pricing-models)
- [Scope-based pricing ›](https://www.revvly.ai/docs/guides/scoped-pricing)
- [Versioning & grandfathering ›](https://www.revvly.ai/docs/guides/versioning)
- [Overriding base & component pricing directly ›](https://www.revvly.ai/docs/guides/override-pricing)
- [Advance vs. arrears billing ›](https://www.revvly.ai/docs/guides/billing-timing)