Subscription Override Line Items

Learn how to customize pricing for specific subscriptions by overriding plan prices with custom amounts, quantities, billing models, and tier structures.

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

Related Topics

• Creating Subscriptions
• Pricing Plans
• Billing Models
• Viewing Subscriptions

---

For technical implementation details, refer to the API Reference.