> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

<small>
  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.
</small>

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

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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

```json theme={null}
{
  "price_id": "price_123",
  "quantity": "5.0"
}
```

### Custom Tiered Pricing

```json theme={null}
{
  "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

```json theme={null}
{
  "price_id": "price_789",
  "billing_model": "PACKAGE",
  "transform_quantity": {
    "divide_by": 25,
    "round": "down"
  }
}
```

### Multiple Overrides

```json theme={null}
{
  "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

```json theme={null}
{
  "price_id": "enterprise_plan",
  "amount": "199.99",
  "quantity": "1.0"
}
```

### Volume Pricing

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/docs/subscriptions/customers-create-subscription)
* [Pricing Plans](/docs/product-catalogue/plans/pricing)
* [Billing Models](/docs/product-catalogue/plans/billing-models/flat-fee)
* [Viewing Subscriptions](/docs/subscriptions/view)

***

*For technical implementation details, refer to the [API Reference](/api-reference/subscriptions/create-subscription).*