One-Time and Event Fees
Two kinds of components bill things that do not recur:
- A one-time fee is charged once, when its trigger happens. Example: a ₹5,000 setup fee.
- A per-event fee is charged each time something happens, and you tell BillHive when. Example: a ₹40 fee for every phone number ported out.
Both are components inside the plan’s price. They are different from the linked charges in your library, which keep working as before. A one-time fee component is an extra, simpler way to add a fee to a plan.
One-time fee
Add one in the rate plan builder
Turn on the tile
In the rate plan builder, under Pricing pieces in this plan, click One-time fee. The section One-time fees · charged once opens.
Add the fee
Click + Add a one-time fee and fill in:
| Field | Description |
|---|---|
| Fee name | Shown on the invoice. Required. Error: Enter a name. |
| Amount (currency) | The fee. Up to 6 decimals. |
| Charged | When the fee is billed. See the table below. |
Choose when it is charged
The Charged list in the builder offers three triggers:
| Option in the builder | API triggerCondition | When it is billed |
|---|---|---|
| When the subscription is created | Subscription Creation | On the first order of the subscription. |
| When the plan or billing frequency changes | Plan Activation | On the order of a plan or frequency change. |
| On demand (charged by an API call) | On Demand | When you charge it with the charges API. |
The API accepts all seven trigger values: Subscription Creation, Subscription Trial Start, Plan Activation, Subscription Activation, Contract Termination, Immediately and On Demand. The builder shows three.
Publish
Click Publish plan. Use Remove to delete a fee.
The builder also shows your library fees as tiles under One-time fees. Click one to link it to the plan. Library fees keep the price set on their own page.
Settings
| Setting | API field | Allowed values | Default | Rules |
|---|---|---|---|---|
| Type | chargeType | ONE_TIME | none | |
| Trigger | triggerCondition | One of the seven values above | none | Required. Error: Component N ONE_TIME needs a valid triggerCondition. On any other type: Component N triggerCondition is only allowed on ONE_TIME components. |
| Amount | flatAmount (or unitPrice) | Number | none | A flat one-time component is billed once, not once per seat. |
| Pass-through | passThrough | true or false | false | See Pass-Through Charges. |
A one-time component ignores minimum and cap, proration and cycles. It is not part of MRR.
Example
A setup fee of ₹5,000 with the trigger When the subscription is created, on a ₹15 a month plan. GST 18%.
First invoice
| Line | Amount | GST 18% |
|---|---|---|
| Rate plan | ₹15.00 | ₹2.70 |
| Setup fee | ₹5,000.00 | ₹900.00 |
| Subtotal | ₹5,015.00 | |
| GST | ₹902.70 | |
| Total | ₹5,917.70 |
The next renewal invoice has no setup fee line.
Per-event fee
Add one in the rate plan builder
Turn on the tile
Click Per-event fee under Pricing pieces in this plan.
Fill in the fee
Click + Add another per-event fee if you need more than one.
| Field | Description |
|---|---|
| Per-event fee name | Shown on the invoice. Error: Enter a name. |
| Price per event (currency) | The price of one occurrence. Error: Price per event must be above 0. |
| Pass through at cost | Tick to mark the line as a pass-through charge. |
A note under the fee reads Charged each time it happens, through the charges API; it is not on the first invoice.
Publish
Click Publish plan.
Settings
| Setting | API field | Allowed values | Default | Rules |
|---|---|---|---|---|
| Type | chargeType | EVENT | none | Always billed in arrears. |
| Charge model | chargeModel | FLAT or PER_UNIT, or a tiered model | none | |
| Price per occurrence | flatAmount (FLAT) or unitPrice (PER_UNIT) | Number above 0 | none | Error: Component N EVENT needs a unitPrice or flatAmount (the price per occurrence). Tiered models over the count are allowed. |
| Pass-through | passThrough | true or false | false |
An event component is rated like usage and is never prorated. For a FLAT event the price per occurrence is its flatAmount.
Charge an event fee
You tell BillHive about each occurrence with the charges API. The charge is stored as a pending charge and is added to the next invoice of the subscription: a renewal, a plan change, or the final bill.
You can also create an ad-hoc charge with a name and an amount, for something that is not in the price list, such as a one-off report.
Endpoints
| Action | Endpoint | Scope |
|---|---|---|
| Create a pending charge | POST /subscriptions/{id}/charges | Subscription.create |
| List pending charges | GET /subscriptions/{id}/charges | Subscription.findById |
| Cancel a pending charge | DELETE /subscriptions/{id}/charges/{chargeId} | Subscription.cancel |
Create a charge for a component
The component must be an event component, or a one-time component with the trigger On Demand, and must belong to the subscription’s current price.
curl -X POST $BILLHIVE_API/subscriptions/3f1c2a64-9a1e-4a58-8d52-0f5d6a9d2b11/charges \
-H "x-api-key: $BILLHIVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"componentId": "c7b5a1de-5b1a-4a86-9d25-4a1b5f3a0e22",
"quantity": 2
}'{
"id": "b1e7f6a0-2b0d-4f7c-9a53-7a0b3d9c1f10",
"tenantId": "9d2c6b0e-1c1f-4c2e-8a4a-0e6c1d7f5a33",
"subscriptionId": "3f1c2a64-9a1e-4a58-8d52-0f5d6a9d2b11",
"componentId": "c7b5a1de-5b1a-4a86-9d25-4a1b5f3a0e22",
"name": "Port-out",
"quantity": 2,
"unitPrice": 40,
"amount": 80,
"passThrough": false,
"status": "PENDING",
"createdTs": "2026-11-14T09:30:00.000Z"
}The amount is worked out by the rating engine when you create the charge. The stored unitPrice is the effective price, amount ÷ quantity.
Create an ad-hoc charge
curl -X POST $BILLHIVE_API/subscriptions/3f1c2a64-9a1e-4a58-8d52-0f5d6a9d2b11/charges \
-H "x-api-key: $BILLHIVE_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Custom report", "amount": 2000, "passThrough": false }'{
"id": "0a9d4c52-7c1e-4d3a-b2f1-6e8a5b7c9d01",
"subscriptionId": "3f1c2a64-9a1e-4a58-8d52-0f5d6a9d2b11",
"name": "Custom report",
"quantity": 1,
"unitPrice": 2000,
"amount": 2000,
"passThrough": false,
"status": "PENDING",
"createdTs": "2026-11-14T09:31:10.000Z"
}Request body
| Field | For | Type | Required | Rules |
|---|---|---|---|---|
componentId | Component charge | UUID | Yes, for a component charge | Must be a component of the subscription’s current price. Error: componentId is not a component of the subscription's current price. |
quantity | Component charge | Number | Yes | Greater than 0. Error: quantity must be greater than 0. |
name | Ad-hoc charge | Text | Yes | Not empty. Error: name is required for an ad-hoc charge. |
amount | Ad-hoc charge | Number | Yes | Greater than 0. Error: amount must be greater than 0. |
passThrough | Ad-hoc charge | true or false | No | Default false. Error: passThrough must be true or false. |
A FLAT charge is multiplied by the quantity: two port-outs of a ₹40 flat event are ₹80.
List pending charges
GET /subscriptions/{id}/charges?status=PENDING returns the charges, newest first. status is optional and can be PENDING, BILLED or CANCELLED. Any other value gives 422 with status must be one of PENDING, BILLED, CANCELLED.
[
{
"id": "b1e7f6a0-2b0d-4f7c-9a53-7a0b3d9c1f10",
"componentId": "c7b5a1de-5b1a-4a86-9d25-4a1b5f3a0e22",
"name": "Port-out",
"quantity": 2,
"unitPrice": 40,
"amount": 80,
"passThrough": false,
"status": "BILLED",
"orderId": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
"createdTs": "2026-11-14T09:30:00.000Z"
}
]Cancel a pending charge
DELETE /subscriptions/{id}/charges/{chargeId} returns the cancelled charge with status CANCELLED. A cancelled charge stays off the next invoice.
Errors
| Status | When | Message |
|---|---|---|
| 404 | The subscription is not yours or does not exist | Subscription not found |
| 404 | The charge does not exist (delete) | Charge not found |
| 409 | The charge is not PENDING any more (delete) | Only a PENDING charge can be cancelled |
| 422 | The subscription is Cancelled, Expired or Trial Expired | The subscription is <status>: a charge can no longer be billed |
| 422 | A final bill is due | The subscription is expiring: its final bill is under way, or The subscription's cancellation has taken effect: its final bill is under way |
| 422 | The subscription has no active price | The subscription has no active price |
| 422 | The component is not chargeable | Only EVENT or On Demand ONE_TIME components can be charged |
| 422 | Bad body | The messages in the table above |
How a charge lands on an invoice
- The next order that is invoiced for the subscription claims every
PENDINGcharge in one step, adds a line for each, and sets them toBILLEDwith its order id. Two orders can never claim the same charge, so a retry does not bill twice. - The line takes the price’s tax settings, and when the charge is pass-through it follows the GST switch.
- A pending charge is claimed by a renewal, by a plan or frequency change that takes effect now, and by the final bill. On a plan with only in-advance recurring lines it is claimed onto the early renewal invoice.
- If the order is cancelled with nothing collectable on it, its charges go back to the subscription and stay
PENDING.
Example, two port-outs
Plan: ₹15 a month, a ₹40 Port-out event fee. You charge two port-outs in the month. GST 18%.
| Line | Qty | Amount | GST 18% |
|---|---|---|---|
| Rate plan | 1 | ₹15.00 | ₹2.70 |
| Port-out | 2 | ₹80.00 | ₹14.40 |
| Subtotal | ₹95.00 | ||
| GST | ₹17.10 | ||
| Total | ₹112.10 |
Both charges now show BILLED with that order’s id. An ad-hoc “Custom report” of ₹2,000 would be a further line with ₹360 of GST.
Limits
- An event component is billed only through the charges API. It is not on the first invoice and not in the builder’s preview.
- Event, one-time, pending and pass-through amounts are not MRR.
- Voiding an invoice after a cancel does not hand the usage or pending charges back to the subscription.
- The cancel API accepts a request without
refundableCreditAction, and the order then fails in the workflow. Always send it.