---
title: "Agreements and price changes"
url: /commerce/agreements
---

# Agreements and price changes

> The terms one Customer signs beyond the posted Offer, and the rules that carry every price change to every Customer.

An agreement adds terms one Customer accepts beyond the Offer: a commitment, a service level with credits, and the rules for price changes.

**An agreement, from template to renewal.** A template in the file.

1. Drafted: for one Customer.
2. Sent (a person sends): for signature. Or declined: Offer stands.
3. Signed (click, sign or call): in signer order.
4. Active (its start date): commits draw.
5. True-up (a shortfall): at the term's end.
6. Renewed (its end date): or ended.

The posted price stays the ceiling throughout.

## Agreements
Templates live in your file under `agreements`, and each Customer's copy is a versioned instance.

A Customer accepts its instance by click, by signature, or through an agent in the call.

| Part | What it does |
| --- | --- |
| Templates | The text in your file, checked at each deploy, with the plans each one covers |
| Instances | One per Customer, engagement or supplier, versioned; a new template version reaches an instance only when its Customer accepts it |
| Acceptance | `click` in the portal; `signature` as an envelope with signer order and an audit trail; `call` by an agent whose mandate covers the agreement |
| Overrides | A price, a payment term, a service level or data terms for one Customer, layered over the Offer as an [extension](/identity/tenancy.md) layers over the file |
| The posted ceiling | No override sells above the posted price, and the [offer card](/reference/contract.md#documents) says when private terms exist |

| Thing | States | What moves it |
| --- | --- | --- |
| An agreement | `drafted`, `sent`, then `signed` or `declined`; a signed one is `active`, then `ended` | A person on your team drafts it from a template; the Customer's signers sign in order; the term's dates |
| A commitment | `active`, then `met` or `short`, then `trued_up` | Spend against each period's amount; the true-up invoice at the term's end |
| An invoice | `draft`, `open`, then `paid` or `void`; a credit note against a paid one | The cycle closes each period; a preview shows the next one at any time |
| A failed renewal | `retrying`, `grace`, then `recovered` or `degraded` | Stripe's retries; `dunning.grace`; the plan `dunning.then` names |
| A price change | `announced`, then `applied`; per Customer, `grandfathered` until its date | `changes.notice`, then `changes.grandfather` |

## Commitments
A commitment is spend promised over a term: an amount per period, ramps that raise it, an overage rate and a true-up.

Calls draw the commitment down at its agreed rate. Past it, overage bills at the rate the agreement names, never above the posted price.

At the term's end, a shortfall bills once as the true-up, or rolls into the next term where the agreement says so.

## Service levels and credits
A service level is the promise in `operate` sold as a term: a metric, a target, a window, and the credit a miss earns.

The [Verifier](/reference/platform.md#verifier) measures it from outside, per Verb. A missed window writes an Event, and its credit lands on the Customer's next invoice with no claim.

## Price models and price changes
Beyond a price per call, an Offer prices by tier, and every price change reaches Customers by its notice rule.

| Model | How it bills |
| --- | --- |
| Graduated | Each unit at the price of its own tier |
| Volume | Every unit at the tier the period's total reaches |
| Package | A credit pack: a price for a fixed amount, from `credits` |
| Minimum | A plan's month price, with its `includes` drawn first |

| Change | How it reaches a Customer |
| --- | --- |
| A lower price | At once, on every [Interface](/every-product.md) and the next call |
| A higher price per call | A breaking change: a new [Version](/reference/platform.md#version), after `changes.notice` |
| A plan's price | At renewal after the notice; a Customer inside `changes.grandfather` keeps its price until that date |
| A failed renewal | Stripe's retries, then `dunning.grace`, then the plan `dunning.then` names; nothing is deleted |

```ts title="definition.ts"
import { define } from 'apis.dev'

/** Deals for each Customer, with a signed agreement and a service level for the largest. */
export default define({
  name: 'pipeline', domain: 'pipeline.apis.dev',
  Company: { name: 'string', domain: 'url!#', deals: '<-Deal.company' },
  Deal: {
    title: 'string', amount: 'decimal(12,2)', company: '->Company.deals',
    stage: { open: [], qualify: 'opened', win: 'qualified', lose: ['opened', 'qualified'] },
  },
  offer: {
    Team: { month: 49, seats: 5, seat: 9, includes: { 'Deal.open': 1000 } },
    Enterprise: { contact: true },
    'Deal.open': { graduated: [{ upTo: 100000, price: 0.001 }, { price: 0.0005 }] },
    agreements: { msa: { file: './agreements/msa.md', accept: 'signature', plans: ['Enterprise'] } },
    terms: { sla: { credit: 0.1, window: 'month', plans: ['Enterprise'] } },
    changes: { notice: '30d', grandfather: '365d' },
    dunning: { grace: '14d', then: 'Team' },
  },
  operate: { promise: { 'Deal.open': { success: 0.999, median: '1s' } } },
})
```

---

The posted price is the most any agreement charges, so a private agreement never costs a Customer more than the public Offer.