Skip to main content

​
Subscription Override Line Items

Subscription override line items allow you to customize pricing for specific subscriptions by overriding the default plan prices. This feature is useful when you need to offer special pricing, bulk discounts, or custom billing arrangements for individual customers.

​
Overview

Override line items enable you to modify various aspects of a subscription’s pricing:
  • Quantity: Override the default quantity for a specific price
  • Amount: Set custom pricing amounts for specific line items
  • Billing Model: Change the billing model for a specific price
  • Tier Mode: Modify how tiered pricing is calculated
  • Tiers: Define custom pricing tiers for the subscription
  • Transform Quantity: Apply quantity transformations for package pricing

​
When to Use Override Line Items

Use override line items in these scenarios:
  • Custom Pricing: Offer special rates for enterprise customers
  • Bulk Discounts: Provide volume-based pricing adjustments
  • Promotional Offers: Apply temporary pricing changes
  • Contract Negotiations: Honor specific pricing agreements
  • Regional Pricing: Adjust prices based on customer location

​
Structure

Each override line item requires: 
{
  "price_id": "string (required)",
  "quantity": "decimal (optional)",
  "amount": "decimal (optional)",
  "billing_model": "string (optional)",
  "tier_mode": "string (optional)",
  "tiers": "array (optional)",
  "transform_quantity": "object (optional)"
}

​
Required Fields

  • price_id: References the plan price to override (must exist in the selected plan)

​
Optional Fields

  • quantity: Custom quantity for this line item
  • amount: New price amount that overrides the original price
  • billing_model: Override the billing model for this price
  • tier_mode: Change how tiered pricing is calculated
  • tiers: Define custom pricing tiers
  • transform_quantity: Apply quantity transformations

​
Billing Model Overrides

​
Flat Fee Billing Model

When overriding to FLAT_FEE, you must provide either an amount or quantity: 
{
  "price_id": "price_123",
  "billing_model": "FLAT_FEE",
  "amount": "29.99"
}
Use Cases:
  • Fixed monthly fees
  • One-time charges
  • Service-based pricing

​
Tiered Billing Model

When overriding to TIERED, you must provide either tier_mode or tiers: 
{
  "price_id": "price_123",
  "billing_model": "TIERED",
  "tier_mode": "VOLUME",
  "tiers": [
    {
      "up_to": 1000,
      "unit_amount": "0.10",
      "flat_amount": "5.00"
    },
    {
      "up_to": null,
      "unit_amount": "0.08"
    }
  ]
}
Tier Modes:
  • VOLUME: All units priced based on the final tier reached
  • SLAB: Tiers apply progressively as quantity increases
Tier Structure:
  • up_to: Quantity threshold (null for the last tier)
  • unit_amount: Price per unit in this tier
  • flat_amount: Additional flat fee for this tier (optional)

​
Package Billing Model

When overriding to PACKAGE, you must provide transform_quantity: 
{
  "price_id": "price_123",
  "billing_model": "PACKAGE",
  "transform_quantity": {
    "divide_by": 10,
    "round": "up"
  }
}
Transform Quantity Fields:
  • divide_by: Number of units per package (must be > 0)
  • round: Rounding behavior ("up" or "down")
Use Cases:
  • Bulk pricing (e.g., 10 units for $5.00)
  • Resource bundling
  • Simplified billing for large quantities

​
Validation Rules

​
General Requirements

  • At least one override field must be provided
  • All amounts must be non-negative
  • All quantities must be non-negative
  • Price ID must reference a valid price in the selected plan

​
Billing Model Specific Rules

​
Tiered Billing

  • Must provide either tier_mode or tiers
  • If tiers provided, each tier must have a valid unit_amount
  • unit_amount must be a valid decimal number
  • flat_amount (if provided) must be a valid decimal number

​
Package Billing

  • transform_quantity.divide_by must be greater than 0
  • transform_quantity.round must be either "up" or "down"
  • Defaults to "up" if not specified

​
Flat Fee Billing

  • Must provide either amount or quantity

​
Examples

​
Basic Quantity Override

{
  "price_id": "price_123",
  "quantity": "5.0"
}

​
Custom Tiered Pricing

{
  "price_id": "price_456",
  "billing_model": "TIERED",
  "tier_mode": "VOLUME",
  "tiers": [
    {
      "up_to": 100,
      "unit_amount": "1.00"
    },
    {
      "up_to": 500,
      "unit_amount": "0.75"
    },
    {
      "up_to": null,
      "unit_amount": "0.50"
    }
  ]
}

​
Package Pricing with Custom Rounding

{
  "price_id": "price_789",
  "billing_model": "PACKAGE",
  "transform_quantity": {
    "divide_by": 25,
    "round": "down"
  }
}

​
Multiple Overrides

{
  "override_line_items": [
    {
      "price_id": "price_123",
      "amount": "19.99"
    },
    {
      "price_id": "price_456",
      "quantity": "10.0",
      "billing_model": "TIERED",
      "tier_mode": "SLAB",
      "tiers": [
        {
          "up_to": 5,
          "unit_amount": "2.00"
        },
        {
          "up_to": null,
          "unit_amount": "1.50"
        }
      ]
    }
  ]
}

​
Best Practices

​
1. Plan Your Overrides

  • Identify which prices need customization
  • Understand the impact on billing calculations
  • Consider how overrides affect reporting

​
2. Validate Business Logic

  • Ensure override amounts make business sense
  • Verify tier structures are logical
  • Test edge cases with different quantities

​
3. Document Changes

  • Keep records of why overrides were applied
  • Note any special conditions or time limits
  • Update customer contracts if necessary

​
4. Monitor Usage

  • Track how overrides affect revenue
  • Identify patterns in override usage
  • Optimize pricing based on override data

​
Common Use Cases

​
Enterprise Discounts

{
  "price_id": "enterprise_plan",
  "amount": "199.99",
  "quantity": "1.0"
}

​
Volume Pricing

{
  "price_id": "api_calls",
  "billing_model": "TIERED",
  "tier_mode": "VOLUME",
  "tiers": [
    {
      "up_to": 10000,
      "unit_amount": "0.001"
    },
    {
      "up_to": null,
      "unit_amount": "0.0005"
    }
  ]
}

​
Promotional Offers

{
  "price_id": "premium_feature",
  "amount": "0.00",
  "quantity": "1.0"
}

​
Troubleshooting

​
Common Issues

  1. Validation Errors
    • Ensure at least one override field is provided
    • Check that amounts and quantities are non-negative
    • Verify price ID exists in the selected plan
  2. Billing Model Conflicts
    • Tiered billing requires tier configuration
    • Package billing needs transform quantity
    • Flat fee requires amount or quantity
  3. Tier Configuration
    • Validate tier boundaries are logical
    • Ensure last tier has up_to: null
    • Check unit amounts are valid decimals

​
Error Messages

  • “price not found in plan”: Verify the price ID exists in the selected plan
  • “at least one override field must be provided”: Add at least one override field
  • “invalid tier unit amount format”: Ensure tier amounts are valid decimal numbers
  • “transform_quantity.divide_by must be greater than 0”: Set a positive package size
For technical implementation details, refer to the API Reference.
⌘I