SettingsDeveloper & API Keys

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

  1. Click the button to generate a key.
  2. Enter an API Key Name so you can recognise it later, e.g. website-checkout.
  3. Choose the API key type you want to create:
TypeUse it forSub types
Full-Access KeyServer-to-server integrations that create customers, place orders and manage subscriptions—
Read-Only KeyReporting and syncing data out of BillHiveAll, or Restricted with chosen permissions (product catalogue, transactional data)
Publishable KeyCode that runs in a browser, such as an embedded pricing tableAll, Write Key or Update Key
  1. 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:

CallerHeader
Your server, with an API keyx-api-key: <your key>
A signed-in portal userAuthorization: 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 trialEndDate or nextBillingDate, are YYYY-MM-DD.
  • Amounts are numbers in the currency’s main unit (rupees, not paise).
  • Lifecycle actions are POST calls on the subscription, for example POST /subscriptions/{id}/pause.
  • Order calls take a cart of items, each with an itemType (such as Rate Plan), the price’s itemId, and a quantity.

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}'
  • limit and skip page through results: page 3 of 20 is limit: 20, skip: 40.
  • Some resources have a /count endpoint, such as GET /accounts/count, that takes a where parameter.

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."
  }
}
StatusMeaningWhat to do
400The request breaks a business rule, e.g. an action the status doesn’t allowRead message; fix the request
401Missing or invalid credentialsCheck the key or token
403The caller lacks the scopeUse a key or role with the permission
404The resource doesn’t exist for your accountCheck the ID
409A v1 edit of a price that uses v2 settingsUse the v2 API
422The body fails validation, e.g. a missing required fieldRead message; details lists the fields
5xxTemporary server problemRetry 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/place call 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.