Developer Settings & API Overview
Last reviewed: 16 November 2026
This page covers how to connect your systems to BillHive: API keys, authentication, request conventions and errors. The full endpoint list is in the API Reference; ready-to-run calls are in Code Examples.
API keys
Settings > API Keys lists your keys with their Name, Key, Type, Sub Type and Last Modified date.
Creating a key
- Click the button to generate a key.
- Enter an API Key Name so you can recognise it later, e.g.
website-checkout. - Choose the API key type you want to create:
| Type | Use it for | Sub types |
|---|---|---|
| Full-Access Key | Server-to-server integrations that create customers, place orders and manage subscriptions | — |
| Read-Only Key | Reporting and syncing data out of BillHive | All, or Restricted with chosen permissions (product catalogue, transactional data) |
| Publishable Key | Code that runs in a browser, such as an embedded pricing table | All, Write Key or Update Key |
- Save. Copy the key and store it in your secrets manager.
You can delete a key or regenerate it from the list. Regenerating breaks every integration using the old key, so update them straight away.
Security rules.
- Never put a Full-Access key in browser or mobile code. Use a Publishable key there.
- Use one key per integration, so you can revoke one without breaking the others.
- Requests with an API key can’t set custom prices. See Custom Prices on an Order.
Authentication
Every request needs credentials, in one of two forms:
| Caller | Header |
|---|---|
| Your server, with an API key | x-api-key: <your key> |
| A signed-in portal user | Authorization: Bearer <access token> |
A key that is unknown or inactive returns 401 with Unauthorized API Key. A request with no credentials returns 401 with Authorization header not found.
Authorization
What a caller may do is decided by permission scopes, such as Subscription.create or UsageEvent.create. A portal user’s scopes come from their roles; see the Permission Matrix. A request outside the caller’s scopes returns 403.
Base URL and environments
Your base URL is shown in your BillHive account. Test against the sandbox before going live; see Sandbox Environment. The examples in these docs use $BILLHIVE_API for the base URL.
Request conventions
- Send and receive JSON (
Content-Type: application/json). - Dates are ISO 8601. Date-only fields, such as
trialEndDateornextBillingDate, areYYYY-MM-DD. - Amounts are numbers in the currency’s main unit (rupees, not paise).
- Lifecycle actions are
POSTcalls on the subscription, for examplePOST /subscriptions/{id}/pause. - Order calls take a
cartof items, each with anitemType(such asRate Plan), the price’sitemId, and aquantity.
Filtering and pagination
List endpoints accept a filter query parameter (JSON), with where, order, limit, skip, fields and include:
curl -G "$BILLHIVE_API/accounts" \
-H "x-api-key: $BILLHIVE_KEY" \
--data-urlencode 'filter={"where":{"status":"Active"},"order":["createdOn DESC"],"limit":20,"skip":40}'limitandskippage through results: page 3 of 20 islimit: 20, skip: 40.- Some resources have a
/countendpoint, such asGET /accounts/count, that takes awhereparameter.
Errors
Errors return an HTTP status and a JSON body:
{
"error": {
"statusCode": 400,
"name": "BadRequestError",
"message": "Cannot change the plan of a subscription that is Paused."
}
}| Status | Meaning | What to do |
|---|---|---|
| 400 | The request breaks a business rule, e.g. an action the status doesn’t allow | Read message; fix the request |
| 401 | Missing or invalid credentials | Check the key or token |
| 403 | The caller lacks the scope | Use a key or role with the permission |
| 404 | The resource doesn’t exist for your account | Check the ID |
| 409 | A v1 edit of a price that uses v2 settings | Use the v2 API |
| 422 | The body fails validation, e.g. a missing required field | Read message; details lists the fields |
| 5xx | Temporary server problem | Retry with back-off |
Business-rule messages quoted in these docs, such as “A trial can only be cancelled immediately. To let it run out, turn off Auto Renew.”, are the message you’ll receive.
Idempotency
There is no general idempotency-key header. Plan your retries:
- Usage events are de-duplicated by
eventId, so resending an event is safe. See Usage Events. - Orders are not de-duplicated by the API. If a
POST /orders/placecall times out, look up the account’s orders (GET /orders) before placing it again. - Internally, BillHive’s workflows don’t create a second subscription, invoice or payment request for the same order when a step is retried.
Rate limits
BillHive doesn’t publish per-key rate limits. Batch usage with POST /usage-events/batch rather than sending one call per event, and back off on 429 or 5xx responses.
Webhooks
Settings > Webhooks registers URLs that BillHive calls when events happen. See Webhook for events, payloads and current limits.