# Billing Models Guide

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

:::

Zuplo supports four billing models, each targeting different business needs. You
can mix models on the same pricing page and even within the same plan.

## Fixed monthly quotas

The most common API monetization model. The customer pays a flat monthly price
and gets a fixed number of requests (or other metered units). When the quota is
exhausted, the API returns `403 Forbidden` until the next billing period.

**When to use:** Predictable revenue, simple to explain, works for most B2B SaaS
APIs.

**How customers experience it:** They subscribe, get their API key, and use the
API until their quota runs out. Clear and predictable for budgeting.

### Example: Three-tier SaaS pricing

**Free tier:**

```json
{
  "key": "free",
  "name": "Free",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Free",
      "duration": null,
      "rateCards": [
        {
          "type": "flat_fee",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": null,
          "price": null,
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 1000,
            "isSoftLimit": false,
            "usagePeriod": "P1M"
          }
        }
      ]
    }
  ]
}
```

**Starter — $29/mo, 10,000 requests:**

```json
{
  "key": "starter",
  "name": "Starter",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Starter Monthly",
      "duration": null,
      "rateCards": [
        {
          "type": "flat_fee",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "price": {
            "type": "flat",
            "amount": "29.00"
          },
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 10000,
            "isSoftLimit": false
          }
        }
      ]
    }
  ]
}
```

**Pro — $99/mo, 100,000 requests:**

```json
{
  "key": "pro",
  "name": "Pro",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Pro Monthly",
      "duration": null,
      "rateCards": [
        {
          "type": "flat_fee",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "price": {
            "type": "flat",
            "amount": "99.00"
          },
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 100000,
            "isSoftLimit": false
          }
        }
      ]
    }
  ]
}
```

**Stripe behavior:** At the start of each billing period, Zuplo issues a Stripe
Invoice with a single fixed-price line item; Stripe collects the payment in
advance.

## Pay-as-you-go

:::caution{title="Coming Soon"}

Pay-as-you-go billing is supported by the underlying monetization models, but
the developer portal pricing table experience has not been fully tested for this
billing model yet. If you need pure pay-as-you-go pricing, contact
[support](mailto:support@zuplo.com) to discuss your use case.

:::

No upfront commitment. The customer provides a credit card, uses the API as much
as they want, and is billed monthly in arrears for actual usage.

**When to use:** Low barrier to entry, usage-based AI APIs, developer tools
where usage is unpredictable.

**How customers experience it:** They sign up, add a payment method, and only
pay for what they use. No quota limits, no hard caps.

### Example: Per-request billing

```json
{
  "key": "paygo",
  "name": "Pay As You Go",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Usage-Based",
      "duration": null,
      "rateCards": [
        {
          "type": "usage_based",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "price": {
            "type": "unit",
            "amount": "0.10"
          },
          "entitlementTemplate": {
            "type": "metered",
            "isSoftLimit": true
          }
        }
      ]
    }
  ]
}
```

Setting `isSoftLimit: true` with no `issueAfterReset` means there is no included
quota and no hard limit — everything is billed per-unit.

### Example: Graduated per-request billing (volume discount)

```json
{
  "key": "paygograduated",
  "name": "Pay As You Go",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Usage-Based",
      "duration": null,
      "rateCards": [
        {
          "type": "usage_based",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "price": {
            "type": "tiered",
            "mode": "graduated",
            "tiers": [
              {
                "upToAmount": "10000",
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.10" }
              },
              {
                "upToAmount": "100000",
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.05" }
              },
              {
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.01" }
              }
            ]
          },
          "entitlementTemplate": {
            "type": "metered",
            "isSoftLimit": true
          }
        }
      ]
    }
  ]
}
```

**Stripe behavior:** At the end of each billing period, Zuplo issues a Stripe
Invoice with usage-based line items in arrears; Stripe collects the payment.

**Risk consideration:** Pay-as-you-go means you're extending credit. If a
customer racks up significant usage and their card declines at invoicing time,
you absorb the loss. Consider setting a hard entitlement limit as a spending cap
if this concerns you.

## Monthly quotas with overages

A hybrid model combining the predictability of fixed quotas with the flexibility
of usage-based billing. The customer pays a fixed monthly price for a base
allowance. If they exceed it, overage is billed per-unit in arrears.

**When to use:** Enterprise APIs, weather data services, any API where you want
guaranteed revenue with upside on heavy usage.

**How customers experience it:** They get a known base cost for budgeting, with
the ability to burst beyond their quota without service interruption.

### Example: Enterprise API with overage

Overage is modeled as graduated tiered pricing. The first tier covers the
included allowance at a flat price, and subsequent tiers charge per-unit for
overage:

```json
{
  "key": "enterprise",
  "name": "Enterprise",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Enterprise Monthly",
      "duration": null,
      "rateCards": [
        {
          "type": "usage_based",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "price": {
            "type": "tiered",
            "mode": "graduated",
            "tiers": [
              {
                "upToAmount": "1000000",
                "flatPrice": { "type": "flat", "amount": "499.00" },
                "unitPrice": null
              },
              {
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.0005" }
              }
            ]
          },
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 1000000,
            "isSoftLimit": true
          }
        }
      ]
    }
  ]
}
```

$499 covers up to 1,000,000 requests. Requests beyond 1M are billed at $0.0005
each. A customer using 1,200,000 requests pays $499 + (200,000 x $0.0005) =
$499 + $100 = $599.

:::note

The $499 sits inside tier 1's `flatPrice`, not as a separate subscription fee.
It's charged unconditionally for the period (regardless of actual usage), but
**in arrears** — it appears on the invoice issued after the end of the billing
period, as part of the invoice's tiered usage line. To collect $499 at the
**start** of every billing period instead (a true in-advance subscription fee),
see [Example: Base fee in advance](#example-base-fee-in-advance) below.

:::

### Example: Graduated overage pricing

For high-volume APIs, you might want overage pricing that decreases at scale:

```json
{
  "key": "enterprise",
  "name": "Enterprise",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Enterprise Monthly",
      "duration": null,
      "rateCards": [
        {
          "type": "usage_based",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "price": {
            "type": "tiered",
            "mode": "graduated",
            "tiers": [
              {
                "upToAmount": "1000000",
                "flatPrice": { "type": "flat", "amount": "499.00" },
                "unitPrice": null
              },
              {
                "upToAmount": "5000000",
                "unitPrice": { "type": "unit", "amount": "0.0005" }
              },
              {
                "unitPrice": { "type": "unit", "amount": "0.0002" }
              }
            ]
          },
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 1000000,
            "isSoftLimit": true
          }
        }
      ]
    }
  ]
}
```

:::note

Like the previous example, the $499 sits inside tier 1's `flatPrice` and is
charged unconditionally for the period in arrears, as part of the invoice's
tiered usage line.

:::

### Example: Base fee in advance

If you need the $499 collected unconditionally at the start of every billing
period (a true subscription fee), split it into a separate `flat_fee` rate card
with `paymentTerm: "in_advance"` and set the usage-based rate card's tier 1 to
$0 per unit for the included quota:

```json
{
  "key": "enterprise",
  "name": "Enterprise",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Enterprise Monthly",
      "duration": null,
      "rateCards": [
        {
          "type": "flat_fee",
          "key": "subscription_fee",
          "name": "Enterprise Subscription",
          "billingCadence": "P1M",
          "price": {
            "type": "flat",
            "amount": "499.00",
            "paymentTerm": "in_advance"
          }
        },
        {
          "type": "usage_based",
          "key": "api_requests",
          "name": "API Calls",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 1000000,
            "isSoftLimit": true
          },
          "price": {
            "type": "tiered",
            "mode": "graduated",
            "tiers": [
              {
                "upToAmount": "1000000",
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.00" }
              },
              {
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.0005" }
              }
            ]
          }
        }
      ]
    }
  ]
}
```

Both patterns charge the customer $499 for every billing period regardless of
usage. The differences are timing and how the fee appears on the invoice:

| Behavior                 | Tier-1 flat price (previous examples)                | Separate flat-fee rate card (this example)                                         |
| ------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
| When the $499 is charged | End of period, in arrears                            | Start of period, in advance                                                        |
| Invoice presentation     | Single tiered usage line item that includes the $499 | Distinct line items: one for the $499, one for usage                               |
| Best for                 | When end-of-period billing is acceptable             | True subscriptions where the fee should be collected upfront and listed separately |

The `subscription_fee` rate card has no `featureKey` — it's a
[rate card without a feature](./rate-cards.mdx#rate-cards-without-features), the
right shape for a billing-only line item that doesn't grant any entitlement.

**Stripe behavior:** At the start of each billing period, Zuplo issues a single
Stripe Invoice that includes both:

- The $499 fixed-price line item from the `subscription_fee` rate card, charged
  in advance for the period that's just starting.
- Any usage-based line items for overage above 1M from the **previous** billing
  period, charged in arrears.

Stripe collects payment for the full invoice. The first billing period's invoice
contains only the $499, since there's no prior period to bill overage for.

## Credits / tokens (prepaid)

:::caution{title="Coming Soon"}

Credit/token-based billing is supported by the underlying monetization models,
but the developer portal experience has not been fully tested for this billing
model yet. If you need prepaid credit billing, contact
[sales@zuplo.com](mailto:sales@zuplo.com) to discuss your use case.

:::

Customers buy credit bundles in advance. Each API call (or token, or byte)
consumes a defined number of credits. When credits are exhausted, service stops
until the customer tops up.

**When to use:** AI APIs, marketplaces, any service where customers want to buy
in bulk at a discount and burn down over time.

**How customers experience it:** They buy a credit pack, use the API until
credits run out, then buy more. No ongoing subscription commitment.

### Example: AI token credit packs

**Small pack:**

```json
{
  "key": "credits_small",
  "name": "50,000 Credits",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Credit Pack",
      "duration": null,
      "rateCards": [
        {
          "type": "flat_fee",
          "key": "api_requests",
          "name": "50,000 API Credits",
          "featureKey": "api_requests",
          "billingCadence": null,
          "price": {
            "type": "flat",
            "amount": "49.00",
            "paymentTerm": "in_advance"
          }
        }
      ]
    }
  ]
}
```

**Large pack (better per-credit rate):**

```json
{
  "key": "credits_large",
  "name": "500,000 Credits",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "default",
      "name": "Credit Pack",
      "duration": null,
      "rateCards": [
        {
          "type": "flat_fee",
          "key": "api_requests",
          "name": "500,000 API Credits",
          "featureKey": "api_requests",
          "billingCadence": null,
          "price": {
            "type": "flat",
            "amount": "299.00",
            "paymentTerm": "in_advance"
          }
        }
      ]
    }
  ]
}
```

**Credit mapping:** Credits are arbitrary units. You define how many credits
each API operation consumes via the `MonetizationInboundPolicy` meter
configuration:

```json
// Simple: 1 credit per request
{ "meters": { "api_credits": 1 } }

// Weighted: different endpoints consume different credits
// (configure separate policies per route)
// /v1/simple-lookup -> 1 credit
{ "meters": { "api_credits": 1 } }
// /v1/ai-analysis -> 10 credits
{ "meters": { "api_credits": 10 } }
```

**Stripe behavior:** One-time payment for the credit pack. Credit balance is
tracked internally. Customers can purchase additional packs at any time
(top-ups).

## Mixing models on one pricing page

You can offer multiple billing models simultaneously. A common pattern:

| Tier         | Model           | Configuration                                             |
| ------------ | --------------- | --------------------------------------------------------- |
| Free         | Fixed quota     | 1,000 requests/month, hard limit, no credit card required |
| Starter      | Fixed quota     | 10,000 requests/month, $29/month, hard limit              |
| Pro          | Quota + overage | 100,000 requests/month, $99/month, $0.001/request overage |
| Enterprise   | Pay-as-you-go   | Volume-discounted per-request pricing, custom terms       |
| Credit Packs | Prepaid credits | Buy 50K/$49, 500K/$299, 5M/$1,999                         |

Each is a separate plan in Zuplo. The Developer Portal displays them together on
the pricing page, and customers choose the model that fits their usage pattern.

## Choosing the right model

| Factor                          | Fixed Quota   | Pay-as-you-go  | Quota + Overage | Credits          |
| ------------------------------- | ------------- | -------------- | --------------- | ---------------- |
| Revenue predictability          | High          | Low            | Medium          | Medium           |
| Customer budget clarity         | High          | Low            | High            | High             |
| Barrier to entry                | Medium        | Low            | Medium          | Low              |
| Revenue upside from heavy users | None          | High           | High            | Medium           |
| Payment risk                    | Low (advance) | High (arrears) | Medium          | None (prepaid)   |
| Best for                        | SaaS APIs     | Dev tools, AI  | Enterprise      | AI, marketplaces |