There are two static factors that influence how your customers are billed.

Their (current) pricing plan
Their (active) promotions

For context, the dynamic factors would include their actual usage, rewards they earned from that usage, etc...

If you need to share a view of the static factors with your customers, you can use the Customer Portal Pricing Plan Details API. In this guide, we will describe this API in a bit more detail.

Pricing Plan

First, a customer is assigned a Pricing Plan (aka. productPlan in the API schema). The Pricing Plan has a static (fixed) component, Fee, and a dynamic (variable) component, Product Item Price.

The following snippet shows the shape of the "product plan" part of the API response. By looking at the productPlan.fees[i]s and the productPlan.productItems[i].productItemPrice.prices one can understand how the customer will be billed given some usage. The price object is explained in "Pricing Engine State Machine".

{
    "productPlan": {
        "id": "...",
        ...
        "fees": [
            {
                "id": "..."
            },
            ...
        ],
        "productItems": [
            {
                "id": "...",
                ...
                "productItemPrice": {
                    "id": "...",
                    "price": {
                        "type": "...",
                        ...
                    }
                }
            },
            ...
        ]
    },
    ...
}

Promotions

A customer may be assigned to multiple Promotions.

The following snippet shows the shape of the "promotions" part of the API response. By looking at promotions[i].promotion, one can see the details of each active promotion of the customer.

{
    ...,
    "promotions": [
        {
            ...,
            "appliedTimeInSeconds": 1655555555,
            "promotion": {
                "id": "...",
                ...
            }
        },
        ...
    ]
}

Appendix: Sample

Here is a sample of a full API response:

{
    "productPlan": {
        "id": "6a00892e-3e02-42c8-9559-6d2e95957848",
        "productId": "1",
        "billingPeriod": {
            "interval": "month",
            "intervalsCount": 1
        },
        "planLevelFreeTier": 10,
        "productPlanName": "Pricing Plan 1",
        "description": "",
        "lastUpdateTimeInMillis": 1654722838307,
        "lockingStatus": "close_to_changes",
        "isDefault": true,
        "successorPlanId": null,
        "transitionStrategy": null,
        "fees": [
            {
                "id": "b9c46a7b-ca07-4164-b2ba-e75a77fdc4e7",
                "name": "Fixed Rate Add-On 1",
                "description": "one time fee",
                "cost": 10,
                "isOneTimeFee": true,
                "isProrated": false,
                "prorateToDay": false,
                "discountable": true,
                "prepayable": true
            }
        ],
        "productItems": [
            {
                "lockingStatus": "close_to_deletions",
                "lastUpdateTimeInMillis": 1654722838307,
                "productItemPrice": {
                    "id": "ab408cd7-3444-4280-b1c5-68b424da4a92",
                    "price": {
                        "type": "PricePerUnitLeafNode",
                        "tiers": [
                            {
                                "startAfterUnit": 100,
                                "batchSize": 1,
                                "pricePerBatch": 2
                            }
                        ],
                        "allowPartialBatch": false
                    },
                    "productItemPriceName": "ab408cd7-3444-4280-b1c5-68b424da4a92",
                    "lockingStatus": "close_to_changes",
                    "lastUpdateTimeInMillis": 1654722838307
                },
                "id": "ef79342b-814c-4df3-bac7-e36875b2c870"
            },
            {
                "lockingStatus": "close_to_deletions",
                "lastUpdateTimeInMillis": 1654722838307,
                "productItemPrice": {
                    "id": "968fdf41-dda1-4f7b-a0c8-d9f5cf86258b",
                    "price": {
                        "type": "max_reducer",
                        "granularity": "hourly",
                        "nextNode": {
                            "type": "LeafNode",
                            "tiers": [
                                {
                                    "startAfterUnit": 1,
                                    "batchSize": 100,
                                    "pricePerBatch": 20
                                },
                                {
                                    "startAfterUnit": 10001,
                                    "batchSize": 100,
                                    "pricePerBatch": 15
                                }
                            ],
                            "allowPartialBatch": false
                        }
                    },
                    "productItemPriceName": "968fdf41-dda1-4f7b-a0c8-d9f5cf86258b",
                    "lockingStatus": "close_to_changes",
                    "lastUpdateTimeInMillis": 1654722838307
                },
                "id": "3ac48ee8-e7f9-4d3c-a7c7-1f2ad0206da3"
            }
        ]
    },
    "promotions": [
        {
            "productId": "1",
            "appliedTimeInSeconds": 1654723079,
            "promotion": {
                "targetProductItemId": "ef79342b-814c-4df3-bac7-e36875b2c870",
                "promotionTimeLimit": {
                    "cycles": 1,
                    "months": 0
                },
                "discount": 50,
                "totalMaxDiscount": null,
                "id": "a21bc4d7-a826-4895-a92d-5bde340bd0e3",
                "type": "time_limited_absolute_item_discount",
                "promotionName": "Promotion 2",
                "description": "",
                "lockingStatus": "close_to_changes",
                "lastUpdateTimeInMillis": 1654722948604
            }
        }
    ]
}