Code Examples
Last reviewed: 16 November 2026
Working calls for the most common integration tasks. They use two shell variables:
export BILLHIVE_API="https://<your-billhive-api-host>" # see Sandbox Environment
export BILLHIVE_KEY="<a Full-Access API key>"Authentication, errors and pagination are explained in Developer Settings & API Overview. Every endpoint and field is in the API Reference.
Create a customer account
curl -X POST "$BILLHIVE_API/accounts" \
-H "x-api-key: $BILLHIVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Pvt Ltd",
"accountType": "Organisation",
"email": "[email protected]",
"phone": "+919800000000",
"address": "12 MG Road",
"city": "Bengaluru",
"state": "Karnataka",
"zipCode": "560001",
"country": "India",
"currency": "INR",
"netTermDays": 15
}'The response contains the new accountId. Use it in the calls below.
Preview the price of a new subscription
POST /orders/estimate prices an order without creating anything. Use the rate plan price ID (one currency and billing frequency of a plan) as itemId.
curl -X POST "$BILLHIVE_API/orders/estimate" \
-H "x-api-key: $BILLHIVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"srcSysCode": "API",
"eventType": "NEW SUBSCRIPTION",
"currency": "INR",
"personalInfo": { "accountId": "<accountId>" },
"cart": [
{ "itemType": "Rate Plan", "itemId": "<ratePlanPriceId>", "quantity": 1, "options": { "billingCycle": 1 } }
]
}'The response’s cart holds each priced line with its amount, fromDate and toDate, plus taxes and totals.
Create a subscription
POST /{accountId}/subscriptions places the order and starts the subscription’s workflow. The body is the same as the estimate.
curl -X POST "$BILLHIVE_API/<accountId>/subscriptions" \
-H "x-api-key: $BILLHIVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"srcSysCode": "API",
"currency": "INR",
"personalInfo": { "accountId": "<accountId>" },
"cart": [
{ "itemType": "Rate Plan", "itemId": "<ratePlanPriceId>", "quantity": 1, "options": { "billingCycle": 1 } }
]
}'The response is the order. The subscription is created by a background workflow a moment later; read it with GET /subscriptions?filter=... or wait for the Subscription Activated webhook.
Send usage
curl -X POST "$BILLHIVE_API/usage-events" \
-H "x-api-key: $BILLHIVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"eventId": "txn_12345_20261116143000",
"eventType": "api_call",
"subscriptionId": "<subscriptionId>",
"accountId": "<accountId>",
"quantity": 1,
"eventTimestamp": "2026-11-16T14:30:00Z",
"source": "API",
"properties": { "endpoint": "/v1/translate" }
}'Resending the same eventId is safe; the duplicate is rejected. For many events use POST /usage-events/batch with { "events": [ ... ] }. See Usage Events.
List a customer’s invoices
curl -G "$BILLHIVE_API/invoices" \
-H "x-api-key: $BILLHIVE_KEY" \
--data-urlencode 'filter={"where":{"accountId":"<accountId>"},"order":["createdTs DESC"],"limit":10}'Download one as a PDF with GET /invoices/{invoiceId}/download.
Subscription actions
| Action | Call | Body |
|---|---|---|
| Pause on a date | POST /subscriptions/{id}/pause | {"pauseOption": "Specific Date", "pauseDate": "2026-12-01", "resumeDate": "2027-01-01"} |
| Resume | POST /subscriptions/{id}/resume | See Pause & Resume |
| Remove a scheduled pause | POST /subscriptions/{subscriptionId}/remove-scheduled-pause | {} |
| Cancel at end of term | POST /subscriptions/{subscriptionId}/cancel | {"cancelOption": "End of Term", "cancellationReason": "Found a cheaper alternative"} |
| Cancel on a date | same | {"cancelOption": "Specific Date", "cancelDate": "2026-12-15", "cancellationReason": "..."} |
| Remove a scheduled cancellation | POST /subscriptions/{subscriptionId}/remove-scheduled-cancellation | {} |
| Extend a trial | POST /subscriptions/{subscriptionId}/extend-trial | {"trialEndDate": "2026-12-31"} |
| Convert a trial now | POST /subscriptions/{subscriptionId}/convert-trial | {} |
| Reactivate | POST /subscriptions/{subscriptionId}/reactivate | {} |
| Renew | POST /subscriptions/{subscriptionId}/renew | {} |
| Move the next billing date | PATCH /subscriptions/{subscriptionId}/next-billing-date | {"nextBillingDate": "2026-12-20"} |
| Add a one-off charge | POST /subscriptions/{id}/charges | See Charge an event fee |
Every action is checked against the subscription’s status. A disallowed action returns 400, e.g. Cannot pause a subscription that is Trial. See Actions by status.
Receive webhooks
const express = require('express');
const app = express();
app.post('/webhooks/billhive', express.json(), async (req, res) => {
const { event, data } = req.body; // event is e.g. "Subscription Cancelled"
switch (event) {
case 'Subscription Activated':
case 'Subscription Renewed':
await grantAccess(data.accountId, data.id);
break;
case 'Subscription Cancelled':
case 'Subscription Expired':
await revokeAccess(data.accountId, data.id);
break;
}
res.sendStatus(200); // answer quickly; BillHive doesn't retry
});
app.listen(3000);Read Webhook before relying on webhooks: only subscription events carry data today, there’s no signature, and a failed delivery isn’t retried.