Revvly
Docs
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 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. 1
    Draft
    You 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. 2
    Published
    Publishing 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. 3
    Effective
    A 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. 4
    Revoked / expired
    Revoke 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. Draft
    Editable, never affects billing.
  2. Published
    Frozen and added to the resolution chain.
  3. Effective
    Applies at the next renewal on or after effectiveFrom.
  4. Revoked
    Override removed at the next renewal.
    or
    Expired
    Archived 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. 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