Code Examples

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

ActionCallBody
Pause on a datePOST /subscriptions/{id}/pause{"pauseOption": "Specific Date", "pauseDate": "2026-12-01", "resumeDate": "2027-01-01"}
ResumePOST /subscriptions/{id}/resumeSee Pause & Resume
Remove a scheduled pausePOST /subscriptions/{subscriptionId}/remove-scheduled-pause{}
Cancel at end of termPOST /subscriptions/{subscriptionId}/cancel{"cancelOption": "End of Term", "cancellationReason": "Found a cheaper alternative"}
Cancel on a datesame{"cancelOption": "Specific Date", "cancelDate": "2026-12-15", "cancellationReason": "..."}
Remove a scheduled cancellationPOST /subscriptions/{subscriptionId}/remove-scheduled-cancellation{}
Extend a trialPOST /subscriptions/{subscriptionId}/extend-trial{"trialEndDate": "2026-12-31"}
Convert a trial nowPOST /subscriptions/{subscriptionId}/convert-trial{}
ReactivatePOST /subscriptions/{subscriptionId}/reactivate{}
RenewPOST /subscriptions/{subscriptionId}/renew{}
Move the next billing datePATCH /subscriptions/{subscriptionId}/next-billing-date{"nextBillingDate": "2026-12-20"}
Add a one-off chargePOST /subscriptions/{id}/chargesSee 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.