Pricing v2 API

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/json

Errors use standard HTTP statuses: 404 not found, 409 conflict, 422 validation, with a message that names the field.

Prices API

ActionEndpointScope
List rate plan pricesGET /v2/rate-plans/{id}/pricesRatePlan.findAllPricesById
Create a rate plan pricePOST /v2/rate-plans/{id}/pricesRatePlan.createPrice
Update a rate plan pricePATCH /v2/rate-plan-prices/{id}RatePlan.updatePriceByPriceId
Delete a rate plan priceDELETE /v2/rate-plan-prices/{id}RatePlanPrice.deleteById
List add-on pricesGET /v2/addons/{id}/pricesAddon.findAllPricesById
Create an add-on pricePOST /v2/addons/{id}/pricesAddon.createPrice
Update an add-on pricePATCH /v2/addon-prices/{id}Addon.updatePriceByPriceId
Delete an add-on priceDELETE /v2/addon-prices/{id}Addon.updatePriceByPriceId
List charge pricesGET /v2/charges/{id}/pricesCharge.findAllPricesById
Create a charge pricePOST /v2/charges/{id}/pricesCharge.createPrice
Update a charge pricePATCH /v2/charge-prices/{id}Charge.updatePriceByPriceId
Delete a charge priceDELETE /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

FieldTypeNotes
chargeTypeRECURRING, USAGE, ONE_TIME, EVENTRequired
chargeModelFLAT, PER_UNIT, VOLUME, GRADUATED, PERCENTAGE, STAIRSTEP, PACKAGERequired
name, unitLabeltext
flatAmount, unitPrice, includedQuantitynumberA non-number gives Component N has an invalid <field>
packageSize, roundingnumber, UP/DOWN/PROPORTIONALPACKAGE only
minAmount, maxAmountnumberNot on FLAT
tiers[{fromUnit, toUnit, unitPrice, flatAmount}]toUnit: null for the last tier
eventType, aggregation, aggProperty, filtersUsage metering
billingTimingIN_ADVANCE, IN_ARREARS
triggerConditionone of 7 valuesONE_TIME only
passThroughbooleanUSAGE, EVENT, ONE_TIME
drawsFromWalletbooleanNeeds 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)

MessageCause
A price needs at least one componentEmpty 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 pricesWallet 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.

FieldType
creditPacks[{pay, credit}], up to 10
grantAmount, grantFrequencynumber above 0, ONCE or EVERY_PERIOD
rolloverboolean, with EVERY_PERIOD only
creditExpiryDaysinteger of 1 or more
walletZeroBalanceActionBILL_OVERAGE, AUTO_TOP_UP, BLOCK
autoTopUpPack, autoTopUpThresholdpack 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 editResult
Description, name, status, trial, tax, display or key editsAllowed
Change price or pricingModel on a price with several components409: 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 settings409: This price uses pricing the v1 API can't edit — use the v2 API
Send wallet fields in a v1 writeRejected
POST /credit-memos with wallet: trueRefused 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.

ActionEndpointScope
CreatePOST /subscriptions/{id}/chargesSubscription.create
List (?status=PENDING|BILLED|CANCELLED)GET /subscriptions/{id}/chargesSubscription.findById
CancelDELETE /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

ActionEndpointScope
A subscription’s walletGET /v2/subscriptions/{id}/walletSubscription.findById
An account’s walletsGET /v2/accounts/{id}/walletSubscription.findById
Top upPOST /v2/subscriptions/{id}/wallet/top-upsSubscription.create
Add creditsPOST /v2/subscriptions/{id}/wallet/adjustmentsCreditMemo.create
Remove an entryDELETE /v2/subscriptions/{id}/wallet/entries/{memoId}CreditMemo.create
Reverse a top-upPOST /v2/wallet/top-ups/{invoiceId}/reverseCreditMemo.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.