Skip to main content
Tiered pricing rewards high-volume subscribers with a lower per-unit rate as they move through successive usage bands. Unlike a simple volume discount that reprices the entire quantity, Subscribd uses graduated tiers: only the portion of units that falls within each band is charged at that band’s rate. This creates a fair, predictable bill that increases smoothly rather than jumping at tier boundaries. Configure tiered plans with rule: 'tiered' and a rule_config.tiers array.

​
Define a tiered plan

Each tier needs three fields:
FieldTypeDescription
up_to`intnull`The inclusive upper bound of this tier. Use null for the final tier (no cap).
unit_amountintPer-unit charge in minor currency units for units within this tier.
flat_amountintOne-time flat fee in minor currency units added when this tier is reached.
config/subscribd.php
'plans' => [
    'api_tiered' => [
        'name'        => 'API (Tiered)',
        'rule'        => 'tiered',
        'price'       => 0,
        'currency'    => 'USD',
        'interval'    => 'month',
        'interval_count' => 1,
        'rule_config' => [
            'tiers' => [
                ['up_to' => 1000,  'unit_amount' => 5,  'flat_amount' => 0],
                ['up_to' => 10000, 'unit_amount' => 3,  'flat_amount' => 2000],
                ['up_to' => null,  'unit_amount' => 1,  'flat_amount' => 5000],
            ],
        ],
        'features' => ['api_calls' => null],
    ],
],
price is set to 0 because the tiers define the entire cost. The price field is required by the schema but has no effect when rule is 'tiered'.

​
How graduated tiers are calculated

For each billing period, Subscribd walks through the tiers in order and charges only the units that fall within each band. The flat fee for the highest tier reached is added once.

​
Worked example: 12,000 API calls

1

Tier 1 — first 1,000 calls at $0.05

The first tier covers units 1 through 1,000.
1,000 × $0.05 = $50.00
No flat fee applies to tier 1 (flat_amount: 0).
2

Tier 2 — next 9,000 calls at $0.03

The second tier covers units 1,001 through 10,000 (9,000 units).
9,000 × $0.03 = $270.00
Reaching tier 2 adds its flat fee once:
flat_amount: 2000 → $20.00
3

Tier 3 — remaining 2,000 calls at $0.01

12,000 total minus the first 10,000 already charged leaves 2,000 units in the final tier.
2,000 × $0.01 = $20.00
Reaching tier 3 (the highest tier) adds its flat fee once:
flat_amount: 5000 → $50.00
4

Total

ComponentAmount
Tier 1: 1,000 × $0.05$50.00
Tier 2: 9,000 × $0.03$270.00
Tier 2 flat fee$20.00
Tier 3: 2,000 × $0.01$20.00
Tier 3 flat fee$50.00
Total$390.00
Only the flat fee for the highest tier reached is charged — not the flat fees of every tier passed through. In the example above, tier 2’s flat fee (20.00)andtier3′sflatfee(20.00) and tier 3's flat fee (50.00) are both applied because tier 3 was reached. If consumption had stopped at 5,000 calls, only tier 2’s flat fee would apply.

​
Reporting usage for tiered plans

Tiered plans that track discrete events (API calls, records processed, etc.) typically pair with metered usage reporting. Use the RecordUsage action to report units during the billing period — Subscribd sums them at period end and applies the graduated tier calculation to produce the invoice. See Metered billing for details on reporting usage with RecordUsage.