Catalogue BuilderCatalogueOne-Time and Event Fees

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:

FieldDescription
Fee nameShown on the invoice. Required. Error: Enter a name.
Amount (currency)The fee. Up to 6 decimals.
ChargedWhen 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 builderAPI triggerConditionWhen it is billed
When the subscription is createdSubscription CreationOn the first order of the subscription.
When the plan or billing frequency changesPlan ActivationOn the order of a plan or frequency change.
On demand (charged by an API call)On DemandWhen 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

SettingAPI fieldAllowed valuesDefaultRules
TypechargeTypeONE_TIMEnone
TriggertriggerConditionOne of the seven values abovenoneRequired. Error: Component N ONE_TIME needs a valid triggerCondition. On any other type: Component N triggerCondition is only allowed on ONE_TIME components.
AmountflatAmount (or unitPrice)NumbernoneA flat one-time component is billed once, not once per seat.
Pass-throughpassThroughtrue or falsefalseSee 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

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

FieldDescription
Per-event fee nameShown 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 costTick 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

SettingAPI fieldAllowed valuesDefaultRules
TypechargeTypeEVENTnoneAlways billed in arrears.
Charge modelchargeModelFLAT or PER_UNIT, or a tiered modelnone
Price per occurrenceflatAmount (FLAT) or unitPrice (PER_UNIT)Number above 0noneError: Component N EVENT needs a unitPrice or flatAmount (the price per occurrence). Tiered models over the count are allowed.
Pass-throughpassThroughtrue or falsefalse

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

ActionEndpointScope
Create a pending chargePOST /subscriptions/{id}/chargesSubscription.create
List pending chargesGET /subscriptions/{id}/chargesSubscription.findById
Cancel a pending chargeDELETE /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

FieldForTypeRequiredRules
componentIdComponent chargeUUIDYes, for a component chargeMust be a component of the subscription’s current price. Error: componentId is not a component of the subscription's current price.
quantityComponent chargeNumberYesGreater than 0. Error: quantity must be greater than 0.
nameAd-hoc chargeTextYesNot empty. Error: name is required for an ad-hoc charge.
amountAd-hoc chargeNumberYesGreater than 0. Error: amount must be greater than 0.
passThroughAd-hoc chargetrue or falseNoDefault 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

StatusWhenMessage
404The subscription is not yours or does not existSubscription not found
404The charge does not exist (delete)Charge not found
409The charge is not PENDING any more (delete)Only a PENDING charge can be cancelled
422The subscription is Cancelled, Expired or Trial ExpiredThe subscription is <status>: a charge can no longer be billed
422A final bill is dueThe subscription is expiring: its final bill is under way, or The subscription's cancellation has taken effect: its final bill is under way
422The subscription has no active priceThe subscription has no active price
422The component is not chargeableOnly EVENT or On Demand ONE_TIME components can be charged
422Bad bodyThe messages in the table above

How a charge lands on an invoice

  • The next order that is invoiced for the subscription claims every PENDING charge in one step, adds a line for each, and sets them to BILLED with 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%.

LineQtyAmountGST 18%
Rate plan1₹15.00₹2.70
Port-out2₹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.