Creating Price Plans

What Is a Price Plan?

A price plan is a named, versioned configuration that defines how to charge customers for usage. It contains:

• Charges — one or more charge definitions, each linking a metric to a pricing model
• Entitlements — feature flags, usage limits, and custom configuration values that activate when a customer subscribes
• Billing metadata — currency, billing period (monthly, annual, or custom), and a display name

Price plans are versioned and immutable. Once you create a plan (or a new version of an existing plan), its charges and entitlements cannot be modified. This guarantees that historical invoices and active subscriptions always reference a stable, unchanging pricing configuration. To update a plan, you create a new version.

The 5 Pricing Models

per_unit

A fixed price per unit of usage. Every unit costs the same amount regardless of how much the customer uses.

1
2
3
4
5

{
  "metric_key": "api_calls",
  "pricing_model": "per_unit",
  "unit_price": 0.0002
}

$0.0002 per API call — 500,000 calls = $100.

tiered

Different unit prices apply to different ranges of usage. Each tier’s price applies only to usage within that range (a “staircase” model). The first N units cost X, the next M units cost Y, and so on.

1
2
3
4
5
6
7
8
9

{
  "metric_key": "api_calls",
  "pricing_model": "tiered",
  "tiers": [
    { "up_to": 100000, "unit_price": 0 },
    { "up_to": 1000000, "unit_price": 0.0001 },
    { "up_to": null, "unit_price": 0.00005 }
  ]
}

First 100k calls are free. Calls 100k–1M cost $0.0001 each. Calls above 1M cost $0.00005 each. up_to: null means “unbounded.”

volume

The customer’s total usage determines which tier they’re in, and that tier’s unit price applies to all units — not just the ones in that range. This rewards higher-volume customers with a better rate on everything they use.

1
2
3
4
5
6
7
8
9

{
  "metric_key": "data_egress_gb",
  "pricing_model": "volume",
  "tiers": [
    { "up_to": 1000, "unit_price": 0.09 },
    { "up_to": 10000, "unit_price": 0.07 },
    { "up_to": null, "unit_price": 0.05 }
  ]
}

A customer using 5,000 GB/month lands in tier 2 and pays $0.07 for all 5,000 GB = $350.

package

Charges are calculated in blocks of N units. Partial blocks are rounded up to the next full block. Useful for “per 1,000 calls” or “per 10 GB” pricing.

1
2
3
4
5
6

{
  "metric_key": "sms_messages",
  "pricing_model": "package",
  "package_size": 1000,
  "package_price": 8.00
}

1,500 SMS messages = 2 blocks (rounded up) = $16.

flat_fee

A fixed amount that doesn’t depend on usage. Use this for base subscription fees, platform access fees, or per-seat fees when seat count is tracked separately. Set metric_key: null for a true flat fee.

1
2
3
4
5
6

{
  "metric_key": null,
  "pricing_model": "flat_fee",
  "amount": 49.00,
  "description": "Growth platform base fee"
}

Mixing Models in One Plan

A single plan can include multiple charges referencing different metrics and pricing models. This is how you build real-world pricing like “base fee + usage”:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

curl -X POST "$ABAXUS_URL/v1/price-plans" \
  -H "Authorization: Bearer $ABAXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "plan_growth",
    "name": "Growth",
    "currency": "usd",
    "billing_period": "monthly",
    "charges": [
      {
        "metric_key": null,
        "pricing_model": "flat_fee",
        "amount": 49.00,
        "description": "Growth base fee"
      },
      {
        "metric_key": "api_calls",
        "pricing_model": "tiered",
        "tiers": [
          { "up_to": 100000, "unit_price": 0 },
          { "up_to": 1000000, "unit_price": 0.0001 },
          { "up_to": null, "unit_price": 0.00005 }
        ]
      },
      {
        "metric_key": "data_egress_gb",
        "pricing_model": "per_unit",
        "unit_price": 0.08
      }
    ],
    "entitlements": [
      { "feature_key": "advanced_analytics", "type": "boolean", "value": true },
      { "feature_key": "api_rate_limit", "type": "limit", "value": 1000 },
      { "feature_key": "support_tier", "type": "custom", "value": "email" }
    ]
  }'

This plan charges $49/month plus tiered API call pricing plus $0.08/GB egress, and grants customers access to advanced analytics, a 1,000 req/min rate limit, and email support.

Plan Immutability — Why It Matters

When Acme Corp signs up for Growth v1, their subscription is pinned to version 1. If you change the tiered pricing in version 2 two months later, Acme’s invoices still use version 1’s tiers. This means:

• Historical invoices are always reproducible
• Customers aren’t surprised by pricing changes mid-period
• You can safely publish new pricing without breaking existing commitments

To update a plan, POST /v1/price-plans with the same id. ABAXUS increments the version automatically and marks the new version as active. Existing subscriptions continue on their pinned version until you schedule a plan change amendment.

Listing Plan Versions

1
2

curl "$ABAXUS_URL/v1/price-plans/plan_growth/versions" \
  -H "Authorization: Bearer $ABAXUS_KEY"

Returns all versions of the plan with their status (active, deprecated), effective dates, and changelog entries.