Price Configuration

The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill.

Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present.

​

Unit pricing

With unit pricing, each unit costs a fixed amount. For example, $0.50 per API call.

{
    ...
    "model_type": "unit",
    "unit_config": {
        "unit_amount": "0.50"
    }
    ...
}

​

Tiered pricing

In tiered pricing, the cost of a given unit depends on the tier range that it falls into, where each tier range is defined by an upper and lower bound. For example, the first ten units may cost $0.50 each and all units thereafter may cost $0.10 each. The first_unit is exclusive while the last_unit is inclusive.

{
    ...
    "model_type": "tiered",
    "tiered_config": {
        "tiers": [
            {
                "first_unit": 0,
                "last_unit": 10,
                "unit_amount": "0.50"
            },
            {
                "first_unit": 10,
                "last_unit": null,
                "unit_amount": "0.10"
            }
        ]
    }
    ...

​

Bulk pricing

Bulk pricing applies when the number of units determine the cost of all units. For example, if you’ve bought less than 10 units, they may each be $0.50 for a total of $5.00. Once you’ve bought more than 10 units, all units may now be priced at $0.40 (i.e. 101 units total would be $40.40).

{
    ...
    "model_type": "bulk",
    "bulk_config": {
        "tiers": [
            {
                "maximum_units": 10,
                "unit_amount": "0.50"
            },
            {
                "maximum_units": 1000,
                "unit_amount": "0.40"
            }
        ]
    }
    ...
}

​

Package pricing

Package pricing defines the size or granularity of a unit for billing purposes. For example, if the package size is set to 10, then 4 units will be billed as 10 and 11 units will be billed at 20.

{
    ...
    "model_type": "package",
    "package_config": {
        "package_amount": "0.80",
        "package_size": 10
    }
    ...
}

​

Matrix pricing

Matrix pricing defines a set of unit prices in a one or two-dimensional matrix. dimensions defines the two event property values evaluated in this pricing model. In a one-dimensional matrix, the second value is null. Every configuration has a list of matrix_values which give the unit prices for specified property values. In a one-dimensional matrix, the matrix values will have dimension_values where the second value of the pair is null. If an event does not match any of the dimension values in the matrix, it will resort to the default_unit_amount. Importantly, the values for the dimension properties sent in the event should always be sent as a string i.e with quotes around them. For example, the pricing is that any call will be $3.00, but if the call is made in the alpha or west region, it will be $2.00.

{
    "model_type": "matrix"
    "matrix_config": {
        "default_unit_amount": "3.00",
        "dimensions": [
            "cluster_name",
            "region"
        ],
        "matrix_values": [
            {
                "dimension_values": [
                    "alpha",
                    "west"
                ],
                "unit_amount": "2.00"
            },
            ...
        ]
    }
}

​

Fixed fees

Fixed fees are prices that are applied independent of usage quantities, and follow unit pricing. They also have an additional parameter fixed_price_quantity. If the Price represents a fixed cost, this represents the quantity of units applied.

{
    ...
    "id": "price_id",
    "model_type": "unit",
    "unit_config": {
        "unit_amount": "2.00"
    },
    "fixed_price_quantity": 3.0
    ...
}