# Pricing Models

:::note{title="Beta"}

API Monetization is in beta and free to try. The APIs are stable but should be
evaluated in non-production environments first. To go to production, contact
[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
announced.

:::

Pricing models define how charges are calculated within a
[rate card](./rate-cards.mdx). Each model suits different business scenarios,
from simple flat fees to complex usage-based pricing.

## Flat Fee Pricing

Flat fee pricing charges a fixed amount regardless of usage. Use `flat_fee` rate
cards for subscriptions, setup fees, or access charges.

### Recurring Subscription

A monthly platform fee that recurs each billing period:

```json
{
  "type": "flat_fee",
  "key": "platform_fee",
  "name": "Platform Fee",
  "billingCadence": "P1M",
  "price": {
    "type": "flat",
    "amount": "99.00"
  }
}
```

### One-Time Setup Fee

A setup fee charged once when the subscription starts (no `billingCadence`):

```json
{
  "type": "flat_fee",
  "key": "setup_fee",
  "name": "Setup Fee",
  "price": {
    "type": "flat",
    "amount": "500.00"
  }
}
```

## Per-Unit Pricing

Per-unit pricing charges a fixed amount for each unit of metered usage. Use
`usage_based` rate cards linked to a feature.

```json
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "unit",
    "amount": "0.001"
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}
```

**Example:** At $0.001 per unit, a customer using 100,000 API calls pays:

`100,000 × $0.001 = $100`

## Tiered Pricing

Tiered pricing varies the price based on usage volume. There are two modes:

### Graduated Pricing

Each unit is charged according to the tier it falls into:

```json
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "tiered",
    "mode": "graduated",
    "tiers": [
      { "upToAmount": 1000, "unitPrice": { "amount": "0.10" } },
      { "upToAmount": 10000, "unitPrice": { "amount": "0.05" } },
      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
    ]
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}
```

| Tier | Units          | Unit Price |
| ---- | -------------- | ---------- |
| 1    | 0 - 1,000      | $0.10      |
| 2    | 1,001 - 10,000 | $0.05      |
| 3    | 10,001+        | $0.01      |

**Example:** A customer using 15,000 units pays:

`(1,000 × $0.10) + (9,000 × $0.05) + (5,000 × $0.01) = $100 + $450 + $50 = $600`

### Volume Pricing

All units are charged at the rate of the highest tier reached:

```json
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "tiered",
    "mode": "volume",
    "tiers": [
      { "upToAmount": 1000, "unitPrice": { "amount": "0.10" } },
      { "upToAmount": 10000, "unitPrice": { "amount": "0.05" } },
      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
    ]
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}
```

**Example:** A customer using 15,000 units pays:

`15,000 × $0.01 = $150`

All units are charged at the tier 3 rate because usage exceeded 10,000.

### Included Usage with Overage

Combine a flat fee for included usage with per-unit overage charges. This is a
common pattern for "X calls included, then $Y per additional call":

```json
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "tiered",
    "mode": "graduated",
    "tiers": [
      { "upToAmount": 10000, "flatPrice": { "amount": "0" } },
      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
    ]
  },
  "entitlementTemplate": {
    "type": "metered",
    "issueAfterReset": 10000,
    "isSoftLimit": true
  }
}
```

This grants 10,000 API calls included (via `issueAfterReset`), then charges
$0.01 per additional call.

## Package Pricing

Package pricing sells usage in fixed bundles rather than individual units:

```json
{
  "type": "usage_based",
  "featureKey": "api_calls",
  "billingCadence": "P1M",
  "price": {
    "type": "package",
    "amount": "10.00",
    "quantityPerPackage": 1000
  },
  "entitlementTemplate": {
    "type": "metered",
    "isSoftLimit": true
  }
}
```

| Usage | Packages | Total |
| ----- | -------- | ----- |
| 0     | 0        | $0    |
| 500   | 1        | $10   |
| 1,000 | 1        | $10   |
| 1,001 | 2        | $20   |
| 5,500 | 6        | $60   |

Usage is rounded up to the next package.

## Choosing a Pricing Model

| Model         | Best For                                                  |
| ------------- | --------------------------------------------------------- |
| **Flat**      | Subscriptions, setup fees, fixed-price features           |
| **Per-Unit**  | Simple usage billing where each unit has equal value      |
| **Graduated** | Volume discounts while maintaining revenue on lower tiers |
| **Volume**    | Aggressive volume discounts to incentivize high usage     |
| **Package**   | Simplified billing, encouraging bulk purchases            |

## Complete Example

See [Plan Examples](./plan-examples.mdx) for step-by-step examples showing how
to build plans with different pricing models.