Build Any Discount Model

54 min

High-level Introduction

Amberflo is designed around flexible, extensible data structures that support a wide range of billing scenarios. This flexibility allows you to define and apply any type of meter, pricing logic, rewards system, or discount model to match your business needs.

This document focuses specifically on the discounts model, and covers the following:

The core discount data structure
The generic discount, which is highly flexible and suitable for advanced use cases
The discount templates, which offer a simpler, more guided configuration experience

The Discount Structure

At a high level, every discount in Amberflo consists of four main components:

Granularity – Defines the level at which the discount is applied, such as invoice-wide or per product item
Condition – Specifies when the discount should apply, based on attributes like customer tags or dimension values
Discount Model – Determines how the discount is calculated, such as a percentage, fixed amount, or tiered structure
Measure – Indicates what metric the discount is applied to (e.g. invoice total, usage quantity, or cost for a specific item)

We will explain these notions in the next sections. For the moment let's start by introducing a high level diagram for the discount structure:

Granularity

In usage-based pricing, an invoice often includes multiple pricing components. These can range from high-level totals to highly detailed line items:

The total invoice price, before any discounts are applied
The total usage price, which is the sum of all item-level usage charges
The price for a specific invoiced item, which in turn may be broken down further by dimension variants
The total fixed fees, made up of individual fee line items

Granularity refers to the specific target of a discount within this structure. It determines which part of the invoice the discount is applied to.

Amberflo currently supports two types of granularity:

Product (or Plan) – Applies the discount to the total invoice amount
Item – Applies the discount to the total cost of a specific invoiced item (for example, a specific product or service)

Support for more granular targets may be added in the future. This could include applying discounts to:

The total usage price across all items
A particular fixed fee
A specific usage variant defined by dimension values

The key point is that every part of the invoice can potentially be targeted by a discount, and the granularity setting determines where the discount is applied.

Condition

The condition defines the rules that determine when and to whom a discount can be applied. It helps answer two key questions:

Can we apply the discount? This checks whether the discount is valid for the customer. It may depend on factors like customer tags, traits, or whether the customer already had the discount applied in a previous billing cycle.
Can the discount be used at this time? Even if the discount is valid for the customer, there may be constraints that prevent it from applying to the current invoice. This could include expiration dates, usage limits, or timing-related rules.

Conditions help ensure that discounts are applied intentionally and contextually, preventing misuse or misapplication across billing cycles.

Below is a diagram describing the existing discount conditions:

Time-Limited Condition

This condition limits a discount for a specified number of billing cycles, a certain number of months, or the mix of both.

If neither cycles nor months is provided, or if promotionTimeLimit is omitted entirely, the discount will have no time limit and will remain active indefinitely.

Schema:

---
type: "object"
properties:
  requiredHistory:
    type: "object"
    properties:
      cycles:
        type: "integer"
        description: "max amount of billing cycles this discount can be applied (optional)"
      months:
        type: "integer"
        description: "max amount of months this discount can be applied (optional)"
  type:
    type: "string"

Same-Plan Condition

A condition for keeping a discount as long as the customer is on same plan as the plan used when applying the discount.

schema:

---
type: "object"
properties:
  type:
    type: "string"
		description: "must be same_plan"

After-Product Price-Threshold Condition

This condition tells the system to begin applying a discount only after the customer has reached a specified product-level billing threshold.

The threshold is calculated as the accumulated total of the customer’s current and previous invoices, based on the time window defined in the requiredHistory setting of the condition.

For example, you can configure a discount to activate once a customer has spent $1,000, regardless of whether it took one billing cycle or several to reach that amount.

This allows for flexible, spend-based discounting that rewards continued or cumulative usage over time.

Schema:

---
type: "object"
properties:
  minThreshold:
    type: "number"
  requiredHistory:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  type:
    type: "string"
    description: "must be after_product_price_threshold"

After-Item Price-Threshold Condition

This condition is very similar to the Product-level Price-Threshold condition. This condition looks at the total price of a specific product item, as opposed to the total price of the entire product usage.

Schema:

---
type: "object"
properties:
  minThreshold:
    type: "number"
  itemId:
  	type: "string"
  requiredHistory:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  type:
    type: "string"
    description: "must be after_item_price_threshold"

Next Billing Cycle

This condition doesn’t restrict whether a discount can be applied. Instead, it simply instructs the system to delay the start of the discount until the next billing cycle following its assignment.

Once the discount is assigned to a customer, it will not affect the current invoice, but will be automatically applied beginning with the next month's billing.

This condition is useful when you want to schedule a discount in advance without applying it retroactively or mid-cycle.

---
type: "object"
properties:
  type:
    type: "string"

No Condition

This special "condition" is just to serve as a placeholder for condition in cases where we don't wish to specify any.

Schema:

---
type: "object"
properties:
  type:
    type: "string"

And Condition

The "and condition" is just a simple way to combine multiple conditions using an 'and' clause.

Schema:

---
type: "object"
properties:
  conditions:
    type: "array"
    items:
      type: "object"
      description: "an array of condition objects"
  type:
    type: "string"
    description: "must be and_condition"

Discount Model

This is the actual discount model we apply on the current invoice.

We currently support the following models:

Model with Max

This is not a standalone discount model, but rather a base structure used by several existing models in the system. It includes optional limits that control how much discount can be applied over time.

A Model with Max allows you to define:

A total maximum discount applied across all billing cycles since the discount began
A maximum discount per billing cycle

These optional caps provide a way to ensure that discount amounts stay within expected boundaries, regardless of usage or billing frequency.

Absolute

The Absolute discount model applies a fixed, constant amount to the bill. The discount can be scoped to either:

A specific product item, or
The entire product bill, depending on the granularity setting

This model is useful for straightforward scenarios, such as subtracting $500 from a customer’s invoice total.

Schema:

---
type: "object"
properties:
  cycleMaxDiscount:
    type: "number"
  discount:
    type: "number"
  measure:
    type: "object"
  requiredHistory:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
		description: "must be and_condition"

Relative

The discount is a constant ratio of the total price (can be for a product item or the entire product bill depending on the granularity).

Schema:

---
type: "object"
properties:
  cycleMaxDiscount:
    type: "number"
  discountRatio:
    type: "number"
  measure:
    type: "object"
  requiredHistory:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"

Tiered absolute

This discount is similar to the absolute case, only in this case the discount amount is determined according to the total invoice price using some predefined discounting tiers.

Schema:

---
type: "object"
properties:
  cycleMaxDiscount:
    type: "number"
  discountValueMap:
    type: "object"
    additionalProperties:
      type: "number"
  measure:
    type: "object"
  requiredHistory:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
		description: "must be price_tiered_absolute"

Example:

{
    "discountValueMap": {
        "50": 1
        "100": 10
    },
    "type": "price_tiered_absolute",
    "measure": {
        "type": "total_price"
    },
    "requiredHistory": {
        "cycles": 0,
        "months": 0
    },
    "totalMaxDiscount": null,
    "cycleMaxDiscount": null
}

The configuration above represents a tiered absolute discount of:

$1 for any total price between $50 to $100.
$10 for any total price of $100 or higher.

Tiered Relative

The Tiered Relative model provides a more flexible way to apply percentage-based discounts. It supports two distinct discounting strategies:

CHOOSE_SINGLE_TIER In this approach, the system evaluates the total discountable price against a set of predefined tiers. Once the appropriate tier is determined, the corresponding discount rate is applied to the entire amount. This method is straightforward and applies a single percentage based on which threshold the total price falls into.
STEP_FUNCTION This strategy works similarly to how income taxes are calculated. The total discountable price is split into intervals, and each interval is discounted separately according to its assigned rate. Each range starts at a defined point (labeled as Ai), and the system applies the matching percentage to each portion of the price within its respective tier.

Then the total discount is: total discount = sum over all Ai-s of Max(0, Min(Ai+1 - Ai, price-value - Ai)) * Discount-Ai

Schema:

---
type: "object"
properties:
  cycleMaxDiscount:
    type: "number"
  discountCalculationStrategy:
    type: "string"
    description: "STEP_FUNCTION, CHOOSE_SINGLE_TIER"
  discountRatioMap:
    type: "object"
    additionalProperties:
      type: "number"
  measure:
    type: "object"
  requiredHistory:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be price_tiered_relative"

For example, let's assume the following tiers:

Now, for a price of $1050.

With CHOOSE_SINGLE_TIER we will calculate a discount of: 1050 * 0.06 = $63 discount

With STEP_FUNCTION we will calculate a discount of: 100 0.00 + (1000 - 100) 0.05 + (1050 - 1000) * 0.06 = 0 + 45 + 3 = $48 discount

Measure

Before diving into the different discount object types, it's important to understand one final, advanced concept: the measure.

A discount model typically operates on the price, but in more advanced use cases, it can also operate on the usage itself. In these cases, the discount is calculated based on the number of invoiced units, using either the average item price or item-specific pricing logic.

This flexibility is key when applying precise, usage-based discounts rather than a flat amount off the total.

Why do we need the measure

Consider a scenario where you want to apply an absolute discount to a specific item invoice. That invoice will usually include:

The total usage amount for the item
The total price charged for that usage

You have several ways to define how the discount should be applied:

TotalPrice: A flat discount amount (e.g., $100) off the total item invoice. This could be scoped at either the product item level or the full product level, depending on granularity.
PerUnit: A discount applied to each unit of usage. For instance, $0.01 off per unit.
PerUnitBatch: A discount applied per batch of usage—for example, $5 off for every 100 units consumed.

This allows for very specific and scalable discount models that align with how your product is used and billed.

Schemas:

Total Price Schema:

---
type: "object"
properties:
  type:
    type: "string"
		description: "must be total_price"

Per Unit Schema:

---
type: "object"
properties:
  type:
    type: "string"
	  description: "must be per_unit"

Per Unit Batch Schema:

---
type: "object"
properties:
  batchSize:
    type: "integer"
  type:
    type: "string"
    description: "must be per_batch"

Generic Discounts

Generic discount models are the most advanced and flexible way to define discounts in Amberflo. These are only available through the API and are designed for cases where none of the standard templates meet your specific requirements.

Because generic discounts require more detailed configuration and validation, we recommend first checking whether a template-based discount can achieve what you need. Use generic discounts only when more control or customization is necessary.

We currently support two types of generic models:

Generic Product Discount

Schema:

---
type: "object"
properties:
  condition:
    type: "object"
  description:
    type: "string"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  promotionModel:
    type: "object"
  promotionName:
    type: "string"
  promotionType:
    type: "string"
    description: "only 'DISCOUNT' is currently supported"
    default: "DISCOUNT"
  targetProductId:
    type: "string"
  type:
    type: "string"
    description: "must be generic_product_promotion"

Example 1:

This is a straightforward example using:

Granularity: Product
Condition: Time-limited
Model: Relative (percentage-based discount)

This is functionally equivalent to the "Time-Limited Relative Product Discount" template, but implemented manually through the generic model structure.

{
    "targetProductId": "ed7a3d38-bdd0-4db2-b047-2bc5d7b67336",
    "promotionType": "discount",
    "condition": {
        "type": "time_limited",
        "requiredHistory": {
            "cycles": 0,
            "months": 1
        }
    },
    "promotionModel": {
        "discountRatio": 0.1,
        "type": "relative",
        "measure": {
            "type": "total_price"
        },
        "requiredHistory": {
            "cycles": 0,
            "months": 1
        },
        "totalMaxDiscount": 100,
        "cycleMaxDiscount": 20
    },
    "id": "6aa33aa2-daf5-47b1-80c0-394127f383e7",
    "type": "generic_product_promotion",
    "promotionName": "55ed6c54-a201-4bfe-aaba-d9bd1b759d7c",
    "lockingStatus": "open"
}

Example 2: This example shows the flexibility of generic models:

A relative discount applied at the product level
Condition 1: The customer must have accumulated at least $10 in product charges over the past 6 months (including the current month)
Condition 2: The discount is only valid for 18 months after it was first applied

While this level of complexity is less common in practice, it illustrates how generic discounts allow for highly tailored business logic.

{
    "targetProductId": "392d5b67-f49d-43c9-979b-89b296063f79",
    "promotionType": "discount",
    "condition": {
        "type": "and_condition",
        "conditions": [
            {
                "type": "after_product_price_threshold",
                "requiredHistory": {
                    "cycles": 0,
                    "months": 6
                },
                "minThreshold": 10
            },
            {
                "type": "time_limited",
                "requiredHistory": {
                    "cycles": 0,
                    "months": 18
                }
            }
        ]
    },
    "promotionModel": {
        "discountRatio": 0.1,
        "type": "relative",
        "measure": {
            "type": "total_price"
        },
        "requiredHistory": {
            "cycles": 0,
            "months": 1
        },
        "totalMaxDiscount": 100,
        "cycleMaxDiscount": 20
    },
    "id": "36577499-d2d2-478d-974a-1f34bc7464e9",
    "type": "generic_product_promotion",
    "promotionName": "0a81c207-6232-4d08-88a1-e877a87c6d53",
    "description": null,
    "lockingStatus": "open",
    "lastUpdateTimeInMillis": 0
}

Generic Item Discount

The GenericItemPromotion model allows you to configure highly specific item-level discounts using advanced logic. Like GenericProductPromotion, this model is only available via the API and is intended for cases where template-based configurations are insufficient.

Schema:

---
type: "object"
properties:
  condition:
    type: "object"
  description:
    type: "string"
  dimensionConstraintMap:
    type: "object"
    description: "A map of dimension key to value (string to string) indicating that this promotion can only be applied against usage that includes the given dimension values."
    additionalProperties:
      type: "string"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  promotionModel:
    type: "object"
  promotionName:
    type: "string"
  promotionType:
    type: "string"
    description: "only 'DISCOUNT' is currently supported"
    default: "DISCOUNT"
  targetItemId:
    type: "string"
  type:
    type: "string"
    description: "must be generic_item_promotion"

Example 1:

This example defines a discount with:

Granularity: Item
Condition: Time-limited
Model: Relative (a percentage-based discount)

Functionally, this is the item-level equivalent of the "Time-Limited Relative Product Discount" template.

{
    "targetItemId": "58e0a665-5244-4d01-8e1e-c0a7a72f169a",
    "promotionType": "discount",
    "condition": {
        "type": "time_limited",
        "requiredHistory": {
            "cycles": 0,
            "months": 1
        }
    },
    "promotionModel": {
        "discountRatio": 0.1,
        "type": "relative",
        "measure": {
            "type": "total_price"
        },
        "requiredHistory": {
            "cycles": 0,
            "months": 1
        },
        "totalMaxDiscount": 100,
        "cycleMaxDiscount": 20
    },
    "id": "50aa986b-d384-4dc4-8a9e-eee1f29f46f5",
    "type": "generic_item_promotion",
    "promotionName": "1675182e-5837-48e7-8df2-41a81aa9815f",
    "lockingStatus": "open",
    "lastUpdateTimeInMillis": 0
}

Example 2:

This builds on the first example but adds a constraint: the discount only applies to usage that matches the following dimension values:

cloudProvider = AWS
region = us-west-2

This setup ensures the discount is only applied to usage tied to specific resource attributes.

{
    "targetItemId": "58e0a665-5244-4d01-8e1e-c0a7a72f169a",
    "promotionType": "discount",
    "condition": {
        "type": "time_limited",
        "requiredHistory": {
            "cycles": 0,
            "months": 1
        }
    },
    "dimensionConstraintMap": {
        "region": "us-west-2",
        "cloudProvider": "AWS"
    },
    "promotionModel": {
        "discountRatio": 0.1,
        "type": "relative",
        "measure": {
            "type": "total_price"
        },
        "requiredHistory": {
            "cycles": 0,
            "months": 1
        },
        "totalMaxDiscount": 100,
        "cycleMaxDiscount": 20
    },
    "id": "50aa986b-d384-4dc4-8a9e-eee1f29f46f5",
    "type": "generic_item_promotion",
    "promotionName": "1675182e-5837-48e7-8df2-41a81aa9815f",
    "lockingStatus": "open",
    "lastUpdateTimeInMillis": 0
}

Example 3: This example demonstrates the full flexibility of the schema by combining multiple conditions:

The total item-level charges must be at least $10 over the last 5 invoices
The total product-level charges must be at least $500 over the same 5 invoices
The pricing plan must remain unchanged during the discount period
The discount expires 12 months after it is first applied

While this level of complexity is not common, it illustrates how generic item-level discounts can be used to enforce detailed billing and usage logic.

{
    "targetItemId": "ca288a7c-9944-41d4-a7e2-d47eabce1496",
    "promotionType": "discount",
    "condition": {
        "type": "and_condition",
        "conditions": [
            {
                "type": "after_item_price_threshold",
                "itemId": null,
                "requiredHistory": {
                    "cycles": 5,
                    "months": 0
                },
                "minThreshold": 10
            },
            {
                "type": "after_product_price_threshold",
                "requiredHistory": {
                    "cycles": 5,
                    "months": 0
                },
                "minThreshold": 500
            },
            {
                "type": "same_plan"
            },
            {
                "type": "time_limited",
                "requiredHistory": {
                    "cycles": 0,
                    "months": 12
                }
            }
        ]
    },
    "promotionModel": {
        "discountRatio": 0.1,
        "type": "relative",
        "measure": {
            "type": "total_price"
        },
        "requiredHistory": {
            "cycles": 10,
            "months": null
        },
        "totalMaxDiscount": 100,
        "cycleMaxDiscount": 20
    },
    "id": "f2aac76a-840a-4608-b268-bae52615e637",
    "type": "generic_item_promotion",
    "promotionName": "d6a2eb2a-91f5-407d-bde9-2bfa2f1d6e7d",
    "description": null,
    "lockingStatus": "open",
    "lastUpdateTimeInMillis": 0
}

Templates

Templates represent the most common and recurring discount patterns. To simplify configuration, Amberflo provides pre-defined templates that wrap these patterns into an easy-to-use structure.

Each template reflects a standard use case that can be quickly customized without requiring manual configuration of advanced fields.

Time-Limited Absolute Product Discount

Granularity: Product
Condition: Time-Limited
Discount Model: Absolute

This template applies a fixed discount amount to the total product-level invoice. The discount is valid for a defined number of billing cycles or months, after which it expires automatically.

Schema:

---
type: "object"
properties:
  description:
    type: "string"
  discount:
    type: "number"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be time_limited_absolute_product_discount"

Example: This discount is valid for 12 months from the moment it is applied to a customer. It targets the entire invoice total and provides:

A maximum of $25 off per invoice
A cumulative maximum of $100 across all invoices while the discount is active

{
    "targetProductId": "4d228d9e-0683-4636-b21f-81c4127298dc",
    "promotionTimeLimit": {
        "cycles": 0,
        "months": 12
    },
    "discount": 25,
    "totalMaxDiscount": 100,
    "id": "10de0900-7751-43f7-a415-fec4fa835009",
    "type": "time_limited_absolute_product_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Time-Limited Absolute Item Discount

Granularity: Item Condition: Time-Limited Discount Model: Absolute

Schema:

---
type: "object"
properties:
  description:
    type: "string"
  dimensionConstraintMap:
    type: "object"
    additionalProperties:
      type: "string"
  discount:
    type: "number"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductItemId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be time_limited_absolute_item_discount"

Example:

This discount is also limited to 12 months from the time it is applied. It targets a single product item (identified as 552a8bf2-864e-4f89-87b0-0962aaec5cdf) and allows:

Up to $10 off per invoice
A total maximum of $50 over the life of the discount

{
    "targetProductItemId": "552a8bf2-864e-4f89-87b0-0962aaec5cdf",
    "promotionTimeLimit": {
        "cycles": 0,
        "months": 12
    },
    "discount": 10,
    "totalMaxDiscount": 500,
    "id": "9d6cb505-bc9a-4ada-8f27-5b39a39428aa",
    "type": "time_limited_absolute_item_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Time-Limited Relative Product Discount

Granularity: Product Condition: Time-Limited Discount Model: Relative

Schema:

---
type: "object"
properties:
  cycleMaxDiscount:
    type: "number"
  description:
    type: "string"
  discountRatio:
    type: "number"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be time_limited_relative_product_discount"

Example:

In this case, the discount is active for 18 billing cycles from the point of application. It gives the customer a 10% discount on the total invoice amount, with an upper limit of $100 total across all invoices during that period.

{
    "targetProductId": "feb90ba8-58a5-4c93-862a-8befc88c31c7",
    "promotionTimeLimit": {
        "cycles": 18,
        "months": 0
    },
    "discountRatio": 0.1,
    "totalMaxDiscount": 100,
    "cycleMaxDiscount": null,
    "id": "db859149-56e5-4b35-8946-96efdff0c7f9",
    "type": "time_limited_relative_product_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Time-Limited Relative Item Discount

Granularity: Item Condition: Time-Limited Discount Model: Relative

Schema:

---
type: "object"
properties:
  cycleMaxDiscount:
    type: "number"
  description:
    type: "string"
  dimensionConstraintMap:
    type: "object"
    description: "A map of dimension key to value (string to string) indicating that this promotion can only be applied against usage that includes the given dimension values."
    additionalProperties:
      type: "string"
  discountRatio:
    type: "number"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductItemId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be time_limited_relative_item_discount"

Example:

This discount is active for 18 billing cycles after it is applied to a customer. It gives a 10% discount on the usage cost of a specific item (acde888f-7720-4138-918d-f9442febc96e) with a total cap of $100 across all invoices while the discount is active.

{
    "targetProductItemId": "acde888f-7720-4138-918d-f9442febc96e",
    "promotionTimeLimit": {
        "cycles": 18,
        "months": 0
    },
    "discountRatio": 0.1,
    "totalMaxDiscount": 100,
    "cycleMaxDiscount": null,
    "id": "768dbdb4-932b-430b-be8c-aae3a9a2c1ca",
    "type": "time_limited_relative_item_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Time-Limited Tiered Absolute Product Discount

Granularity: Product Condition: Time-Limited Discount Model: Tiered-Absolute

Schema:

---
type: "object"
properties:
  acrossBillingPeriods:
    type: "boolean"
    description: "if true then the tier level discount will be detemined using the sum of all invoices since the promotion was applied."
  description:
    type: "string"
  discountMap:
    type: "object"
		additionalProperties:
    	type: "number"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  measure:
    type: "object"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
		description: "must be time_limited_tiered_absolute_product_discount"

Example 1: This discount is not time-limited. It applies to the entire product-level bill using a tiered structure:

$1 discount if the invoice total reaches $1
$2 discount if the invoice total reaches $10

{
    "targetProductId": "1",
    "promotionTimeLimit": {
        "cycles": 0,
        "months": 0
    },
    "discountMap": {
        "1": 1,
        "10": 2
    },
    "totalMaxDiscount": null,
    "id": "c58986fc-ee9f-427c-8163-3695c9dba0e1",
    "type": "time_limited_tiered_absolute_product_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Example 2: This version is limited to 3 months from the time it is applied. The discount uses the same tiered structure:

$1 discount for the first $1 spent per invoice
$2 discount if the total across all invoices since the discount was applied reaches $10 or more

{
    "targetProductId": "1",
    "acrossBillingPeriods": true,
    "promotionTimeLimit": {
        "cycles": 0,
        "months": 0
    },
    "discountMap": {
        "1": 1,
        "10": 2
    },
    "totalMaxDiscount": null,
    "id": "c58986fc-ee9f-427c-8163-3695c9dba0e1",
    "type": "time_limited_tiered_absolute_product_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Time-Limited Tiered Absolute Item Discount

Granularity: Item Condition: Time-Limited Discount Model: Tiered-Absolute

Schema:

---
type: "object"
properties:
  acrossBillingPeriods:
    type: "boolean"
    description: "if true then the tier level discount will be detemined using the sum of all invoices since the promotion was applied."
  description:
    type: "string"
  dimensionConstraintMap:
    type: "object"
    description: "A map of dimension key to value (string to string) indicating that this promotion can only be applied against usage that includes the given dimension values."
    additionalProperties:
      type: "string"
  discountMap:
    type: "object"
		additionalProperties:
    	type: "number"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  measure:
    type: "object"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductItemId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be time_limited_tiered_absolute_item_discount"

Example:

This discount is not limited in time. It applies to the usage bill of item 2d59a1d5-31d7-409d-9d78-843f31eb3e08. The tiered discount provides:

$1 off if the invoice total for the item reaches $1
$2 off if the invoice total reaches $10

{
    "targetProductItemId": "2d59a1d5-31d7-409d-9d78-843f31eb3e08",
    "promotionTimeLimit": {
        "cycles": 0,
        "months": 0
    },
    "discountMap": {
        "1": 1,
        "10": 2
    },
    "totalMaxDiscount": null,
    "id": "4f7c999d-213f-4472-87c1-1b26da690338",
    "type": "time_limited_tiered_absolute_item_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Time-Limited Tiered Relative Product Discount

Granularity: Product Condition: Time-Limited Discount Model: Tiered-Absolute

Schema:

---
type: "object"
properties:
  acrossBillingPeriods:
    type: "boolean"
    description: "if true then the tier level discount will be detemined using the sum of all invoices since the promotion was applied."
  cycleMaxDiscount:
    type: "number"
  description:
    type: "string"
  discountCalculationStrategy:
    type: "string"
    description: "STEP_FUNCTION, CHOOSE_SINGLE_TIER"
  id:
    type: "string"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  priceToDiscountMap:
    type: "object"
		additionalProperties:
    	type: "number"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be time_limited_tiered_relative_product_discount"

Example:

This discount is valid for 18 billing cycles and applies to the entire invoice total. It uses the step_function method to calculate the discount:

10% off the first $10 spent
20% off any amount beyond that

The discount is capped at $19 per cycle and $100 in total over its lifetime.

{
    "targetProductId": "1",
    "promotionTimeLimit": {
        "cycles": 18,
        "months": 0
    },
    "priceToDiscountMap": {
        "0": 0.1,
        "10": 0.2
    },
    "discountCalculationStrategy": "step_function",
    "totalMaxDiscount": 100,
    "cycleMaxDiscount": 19,
    "id": "67a63178-cdd4-48f6-a305-2038033abd9a",
    "type": "time_limited_tiered_relative_product_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}

Time-Limited Tiered Relative Item Discount

Granularity: Item Condition: Time-Limited Discount Model: Tiered-Absolute

Schema:

---
type: "object"
properties:
  acrossBillingPeriods:
    type: "boolean"
    description: "if true then the tier level discount will be detemined using the sum of all invoices since the promotion was applied."
  cycleMaxDiscount:
    type: "number"
  description:
    type: "string"
  dimensionConstraintMap:
    type: "object"
    description: "A map of dimension key to value (string to string) indicating that this promotion can only be applied against usage that includes the given dimension values."
    additionalProperties:
      type: "string"
  discountCalculationStrategy:
    type: "string"
    description: "STEP_FUNCTION, CHOOSE_SINGLE_TIER"
  id:
    type: "string"
  lastUpdateTimeInMillis:
    type: "integer"
  lockingStatus:
    type: "string"
    description: "OPEN, CLOSE_TO_DELETIONS, CLOSE_TO_CHANGES, DEPRECATED"
  priceToDiscountMap:
    type: "object"
		additionalProperties:
    	type: "number"
  promotionName:
    type: "string"
  promotionTimeLimit:
    type: "object"
    properties:
      cycles:
        type: "integer"
      months:
        type: "integer"
  targetProductItemId:
    type: "string"
  totalMaxDiscount:
    type: "number"
  type:
    type: "string"
    description: "must be time_limited_tiered_relative_item_discount"

Example:

This discount is active for 18 billing cycles and targets the usage cost of item 806fdb8e-5bce-4b24-b6ce-ab37ef857e89. Like the previous example, it uses the step_function method:

10% off the first $10 spent
20% off any additional spend

The discount is capped at $25 per cycle and $100 total during its active period.

{
    "targetProductItemId": "806fdb8e-5bce-4b24-b6ce-ab37ef857e89",
    "promotionTimeLimit": {
        "cycles": 18,
        "months": 0
    },
    "priceToDiscountMap": {
        "0": 0.1,
        "10": 0.2
    },
    "discountCalculationStrategy": "step_function",
    "totalMaxDiscount": 100,
    "cycleMaxDiscount": 25,
    "id": "4ba106b9-2ef5-48b5-bc13-24dcf6cd635d",
    "type": "time_limited_tiered_relative_item_discount",
    "promotionName": "my promo",
    "lockingStatus": "open"
}