Pricing v2 API
The v2 APIs read and write prices with their components, rate components for a preview, add pending charges, and manage prepaid wallets. Authenticate like the rest of the API, with an API key or a portal user’s bearer token. See Authentication.
x-api-key: YOUR_API_KEY
Content-Type: application/jsonErrors use standard HTTP statuses: 404 not found, 409 conflict, 422 validation, with a message that names the field.
Prices API
| Action | Endpoint | Scope |
|---|---|---|
| List rate plan prices | GET /v2/rate-plans/{id}/prices | RatePlan.findAllPricesById |
| Create a rate plan price | POST /v2/rate-plans/{id}/prices | RatePlan.createPrice |
| Update a rate plan price | PATCH /v2/rate-plan-prices/{id} | RatePlan.updatePriceByPriceId |
| Delete a rate plan price | DELETE /v2/rate-plan-prices/{id} | RatePlanPrice.deleteById |
| List add-on prices | GET /v2/addons/{id}/prices | Addon.findAllPricesById |
| Create an add-on price | POST /v2/addons/{id}/prices | Addon.createPrice |
| Update an add-on price | PATCH /v2/addon-prices/{id} | Addon.updatePriceByPriceId |
| Delete an add-on price | DELETE /v2/addon-prices/{id} | Addon.updatePriceByPriceId |
| List charge prices | GET /v2/charges/{id}/prices | Charge.findAllPricesById |
| Create a charge price | POST /v2/charges/{id}/prices | Charge.createPrice |
| Update a charge price | PATCH /v2/charge-prices/{id} | Charge.updatePriceByPriceId |
| Delete a charge price | DELETE /v2/charge-prices/{id} | Charge.updatePriceByPriceId |
Create and update take { "pricePoint": { ... }, "components": [ ... ] }. An update replaces all components with the ones you send. PATCH and DELETE answer 204. The {id} of a price can be its id or its key.
Price point fields
name, externalName, currencyCode, billingPeriodId, isTrial, trialPeriodId, taxIncluded, taxProfileId, description, invoiceNote, showDescInInvoice, showDescInQuote, highlightPlan, showStrikethrough, strikethroughPrice, showPrice, ctaButtonBehavior, ctaButtonLabel, customBadge, termLength, autoRenew, requireBillingAtSignup, billingCycle, the price key (ratePlanPriceKey, addonPriceKey or chargePriceKey), productId (on create), passThroughTaxable (default true), and, on rate plan prices only, the wallet settings.
On create, isTrial, requireBillingAtSignup, showDescInInvoice, showDescInQuote and termLength are required, and billingCycle is Fixed or Forever. Any other field is refused with 422 (must NOT have additional properties).
Component fields
| Field | Type | Notes |
|---|---|---|
chargeType | RECURRING, USAGE, ONE_TIME, EVENT | Required |
chargeModel | FLAT, PER_UNIT, VOLUME, GRADUATED, PERCENTAGE, STAIRSTEP, PACKAGE | Required |
name, unitLabel | text | |
flatAmount, unitPrice, includedQuantity | number | A non-number gives Component N has an invalid <field> |
packageSize, rounding | number, UP/DOWN/PROPORTIONAL | PACKAGE only |
minAmount, maxAmount | number | Not on FLAT |
tiers | [{fromUnit, toUnit, unitPrice, flatAmount}] | toUnit: null for the last tier |
eventType, aggregation, aggProperty, filters | Usage metering | |
billingTiming | IN_ADVANCE, IN_ARREARS | |
triggerCondition | one of 7 values | ONE_TIME only |
passThrough | boolean | USAGE, EVENT, ONE_TIME |
drawsFromWallet | boolean | Needs packs or a grant on the price |
Create a rate plan price (request)
A SendGrid-style plan: a ₹15 monthly base plus emails with 15,000 included, a minimum and a cap.
curl -X POST $BILLHIVE_API/v2/rate-plans/6d0f6c1a-3a52-4c5e-9b55-0c2f9b6f1d01/prices \
-H "x-api-key: $BILLHIVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"pricePoint": {
"name": "Basic 5K INR Monthly",
"currencyCode": "INR",
"billingPeriodId": "0b6f2f1e-9d54-4c7a-8a73-6a0f4a8b1c22",
"taxIncluded": false,
"isTrial": false,
"requireBillingAtSignup": false,
"showDescInInvoice": false,
"showDescInQuote": false,
"termLength": 1,
"billingCycle": "Forever",
"passThroughTaxable": true
},
"components": [
{ "chargeType": "RECURRING", "chargeModel": "FLAT", "name": "Base", "flatAmount": 15 },
{
"chargeType": "USAGE", "chargeModel": "PER_UNIT", "name": "Emails", "unitLabel": "email",
"unitPrice": 0.004, "includedQuantity": 15000, "maxAmount": 10,
"eventType": "email_sent", "aggregation": "SUM"
}
]
}'Response
{
"id": "a41b6c9e-52d3-4b7c-8e0a-3d1f9c7b2a55",
"name": "Basic 5K INR Monthly",
"currencyCode": "INR",
"ratePlanId": "6d0f6c1a-3a52-4c5e-9b55-0c2f9b6f1d01",
"status": "DRAFT",
"passThroughTaxable": true,
"components": [
{ "id": "c-1", "chargeType": "RECURRING", "chargeModel": "FLAT", "name": "Base", "flatAmount": 15, "position": 0 },
{ "id": "c-2", "chargeType": "USAGE", "chargeModel": "PER_UNIT", "name": "Emails", "unitPrice": 0.004,
"includedQuantity": 15000, "maxAmount": 10, "eventType": "email_sent", "aggregation": "SUM", "position": 1 }
]
}A new price starts as a draft. The fields shown are the main ones; the response also carries the stored price point fields.
List response
GET /v2/rate-plans/{id}/prices returns an array of price points, each with id and components (with their tiers).
Validation errors (422)
| Message | Cause |
|---|---|
A price needs at least one component | Empty or missing components |
Component N must be an object | |
Component N has an invalid chargeType / chargeModel | |
Component N STAIRSTEP needs at least one tier | |
Component N STAIRSTEP tiers must have a unitPrice of 0 | |
Component N PACKAGE needs a packageSize greater than 0 | |
Component N PACKAGE needs a rounding of UP, DOWN, PROPORTIONAL | |
Component N PACKAGE does not take tiers | |
Component N packageSize is only allowed on PACKAGE components (also rounding) | |
Component N minAmount is not allowed on FLAT components (also maxAmount) | |
Component N minAmount must be a number >= 0 | |
Component N minAmount must not exceed maxAmount | |
Component N has an invalid billingTiming | |
Component N billingTiming IN_ARREARS is only allowed on RECURRING, USAGE or EVENT components | |
Component N billingTiming IN_ADVANCE is only allowed on RECURRING components | |
Component N ONE_TIME needs a valid triggerCondition | |
Component N triggerCondition is only allowed on ONE_TIME components | |
Component N passThrough must be true or false | |
Component N passThrough is only allowed on USAGE, EVENT or ONE_TIME components | |
Component N EVENT needs a unitPrice or flatAmount (the price per occurrence) | |
passThroughTaxable must be true or false | |
Component N drawsFromWallet must be true or false | |
wallet settings are only on rate plan prices | Wallet fields on an add-on or charge price |
404 Price {id} not found when a price to update or delete does not exist; 404 Rate plan {id} not found on create.
Wallet settings on a rate plan price
Put these in pricePoint. null means unset. Full table with builder labels: Prepaid Credits in the Builder.
| Field | Type |
|---|---|
creditPacks | [{pay, credit}], up to 10 |
grantAmount, grantFrequency | number above 0, ONCE or EVERY_PERIOD |
rollover | boolean, with EVERY_PERIOD only |
creditExpiryDays | integer of 1 or more |
walletZeroBalanceAction | BILL_OVERAGE, AUTO_TOP_UP, BLOCK |
autoTopUpPack, autoTopUpThreshold | pack index, number of 0 or more (required with AUTO_TOP_UP) |
{
"pricePoint": {
"creditPacks": [ { "pay": 100, "credit": 105 }, { "pay": 250, "credit": 265 },
{ "pay": 500, "credit": 535 }, { "pay": 1000, "credit": 1080 } ],
"creditExpiryDays": 365,
"walletZeroBalanceAction": "BILL_OVERAGE"
},
"components": [
{ "chargeType": "USAGE", "chargeModel": "PER_UNIT", "name": "SMS", "unitPrice": 0.0083,
"eventType": "sms", "aggregation": "SUM", "drawsFromWallet": true }
]
}Wallet errors (all 422): creditPacks must be an array, creditPacks allows at most 10 packs, creditPacks pay must be greater than 0, creditPacks credit must be at least pay, creditPacks has a duplicate pay of X, grantAmount must be greater than 0, grantFrequency is required with grantAmount: ONCE, EVERY_PERIOD, grantFrequency must be ONCE or EVERY_PERIOD, rollover must be true or false, rollover is only allowed with grantFrequency EVERY_PERIOD, creditExpiryDays must be an integer of at least 1, walletZeroBalanceAction must be BILL_OVERAGE, AUTO_TOP_UP, BLOCK, autoTopUpPack must be the index of a credit pack, autoTopUpThreshold must be a number of at least 0, drawsFromWallet needs the price to have creditPacks or a grantAmount.
v1 is read-only for these settings
The v1 price APIs and the classic form keep working and show a derived single price. They cannot change what the components say.
| v1 edit | Result |
|---|---|
| Description, name, status, trial, tax, display or key edits | Allowed |
Change price or pricingModel on a price with several components | 409: This price has several pricing pieces — edit it in the rate plan builder |
Change price, pricingModel, freeQuantity or tiers on a price that uses a stairstep or package model, a minimum or cap, a one-time or event component, in-arrears recurring, pass-through, or wallet settings | 409: This price uses pricing the v1 API can't edit — use the v2 API |
| Send wallet fields in a v1 write | Rejected |
POST /credit-memos with wallet: true | Refused with 422 |
v1 shows a stairstep price as Volume Pricing at the first step, a package price as Per Unit Pricing at the pack price, and a multi-component price as Hybrid Pricing with the flat amount as the price.
Rate preview: POST /v2/prices/rate
Scope: RatePlan.findAllPricesById. It rates components against quantities and writes nothing. Use it for previews.
Request fields: components (as above), inputs (an object keyed by component id) and defaults (applied to every component). An input has quantity (seats), usage, periodRatio (proration, 0 to 1), cycles and atPurchase (true shows usage as “billed on usage”). A component without an id gets component-0, component-1 and so on.
curl -X POST $BILLHIVE_API/v2/prices/rate \
-H "x-api-key: $BILLHIVE_KEY" -H "Content-Type: application/json" \
-d '{
"components": [
{ "id": "base", "chargeType": "RECURRING", "chargeModel": "FLAT", "name": "Base", "flatAmount": 15 },
{ "id": "emails", "chargeType": "USAGE", "chargeModel": "PER_UNIT", "name": "Emails",
"unitPrice": 0.004, "includedQuantity": 15000 },
{ "id": "api", "chargeType": "USAGE", "chargeModel": "PACKAGE", "name": "API calls",
"packageSize": 1000, "rounding": "UP", "unitPrice": 500 }
],
"inputs": { "emails": { "usage": 18000 }, "api": { "usage": 2500 } }
}'[
{ "componentId": "base", "label": "Base", "quantity": 1, "billableQuantity": 1, "amount": 15, "unitPrice": 15 },
{ "componentId": "emails", "label": "Emails", "quantity": 18000, "billableQuantity": 3000, "amount": 12, "unitPrice": 0.004 },
{ "componentId": "api", "label": "API calls", "quantity": 2500, "billableQuantity": 2500, "amount": 1500, "unitPrice": 500, "packages": 3 }
]A graduated line also returns bands, a stairstep line returns tier, a line changed by a limit returns adjustment (kind MINIMUM or MAXIMUM, and a signed amount), and a pass-through line returns passThrough: true. The component validation errors above apply. The design said POST /v2/prices/:id/rate; the built route is /v2/prices/rate.
Charges API
Pending charges for the next invoice of a subscription. Full request and response examples, the body table and the error list are on One-Time and Event Fees.
| Action | Endpoint | Scope |
|---|---|---|
| Create | POST /subscriptions/{id}/charges | Subscription.create |
List (?status=PENDING|BILLED|CANCELLED) | GET /subscriptions/{id}/charges | Subscription.findById |
| Cancel | DELETE /subscriptions/{id}/charges/{chargeId} | Subscription.cancel |
Body: { "componentId": "...", "quantity": 2 } or { "name": "Custom report", "amount": 2000, "passThrough": false }. Errors: 404, 409 Only a PENDING charge can be cancelled, and 422 for a bad body, a component that cannot be charged, or a subscription that has ended or is on its final bill.
Wallet API
| Action | Endpoint | Scope |
|---|---|---|
| A subscription’s wallet | GET /v2/subscriptions/{id}/wallet | Subscription.findById |
| An account’s wallets | GET /v2/accounts/{id}/wallet | Subscription.findById |
| Top up | POST /v2/subscriptions/{id}/wallet/top-ups | Subscription.create |
| Add credits | POST /v2/subscriptions/{id}/wallet/adjustments | CreditMemo.create |
| Remove an entry | DELETE /v2/subscriptions/{id}/wallet/entries/{memoId} | CreditMemo.create |
| Reverse a top-up | POST /v2/wallet/top-ups/{invoiceId}/reverse | CreditMemo.create |
The design had the top-up and adjustment routes without the /v2 prefix. The built routes have it.
Get a subscription’s wallet
{
"balance": 105,
"projected": 92.5,
"walletExhausted": false,
"entries": [
{ "id": "m-2", "sourceType": "Wallet Bonus", "amount": 5, "balance": 5, "effectiveDate": "2026-11-14",
"expiresOn": "2027-11-14", "status": "Posted", "wallet": true },
{ "id": "m-1", "sourceType": "Wallet Top-up", "amount": 100, "balance": 100, "effectiveDate": "2026-11-14",
"expiresOn": null, "status": "Posted", "wallet": true }
],
"upcomingExpiries": [ { "memoId": "m-2", "expiresOn": "2027-11-14", "amount": 5 } ]
}balance is the usable balance. projected is the balance less this term’s unbilled usage and pending charges on components paid from credits. projectedUnavailable: true is added when the usage could not be computed, and projected is then the balance. Entries are newest first.
Get an account’s wallets
{
"subscriptions": [ { "id": "3f1c2a64-9a1e-4a58-8d52-0f5d6a9d2b11", "balance": 105 } ],
"carriedOver": 26.9,
"total": 131.9
}Top up
Body: { "packIndex": 0 } for a pack, or { "amount": 250 } for a custom amount with no bonus.
curl -X POST $BILLHIVE_API/v2/subscriptions/3f1c2a64-9a1e-4a58-8d52-0f5d6a9d2b11/wallet/top-ups \
-H "x-api-key: $BILLHIVE_KEY" -H "Content-Type: application/json" -d '{ "packIndex": 0 }'The response holds the new order, its invoice (₹100 plus ₹18 GST for pack 0 of the example) and the payment session:
{
"order": { "id": "o-1", "eventType": "WALLET TOP-UP", "dueAmount": 118 },
"invoice": { "id": "inv-1" },
"pgOrderId": "order_123",
"paymentSessionId": "session_abc",
"pgOrderExpiryTime": 1731580800000
}Credits are posted when the invoice is paid. Errors (422): currency: the subscription is billed in INR, packIndex: the price has no credit packs, packIndex: not a pack of the price, packIndex or an amount greater than 0 is required, The subscription has no active price.
Add credits
{ "amount": 50, "reason": "Goodwill" } returns the new credit memo (sourceType Wallet Adjustment). Errors (422): amount must be greater than 0, reason is required.
Remove an entry
Returns { "removed": 20 }. 404 Wallet entry not found when the entry is not on that subscription.
Reverse a top-up
Returns { "removed": 65, "charged": 35, "alreadyReversed": false }. 404 No wallet top-up was posted for that invoice. Calling it again returns alreadyReversed: true and changes nothing. See Top-Ups and Adjustments.
All wallet routes answer 404 Subscription not found for a subscription that is not yours.