Billing

The plan catalog you sell, and metering what a subscriber consumes.

Rendering pricing. GET /plans returns your active plans so a partner-hosted pricing page stays correct through a price change instead of hardcoding one. A monthly and an annual plan sharing a planGroup are one tier at two cadences - group on that field, never on name.

const { plans } = await connect.billing.listPlans();
const tiers = groupBy(plans, (plan) => plan.planGroup);

Metering an add-on. A consumable add-on carries a per-cycle balance. Read it, then debit it as your users consume:

const { addons } = await connect.billing.getAddonUsage(workspaceId);
const credits = addons.find((addon) => addon.addonId === "extra_messages");

await connect.billing.consumeAddon({
  workspaceId,
  addonId: "extra_messages",
  quantity: 1,
  // Same key on a retry debits once. Send one per unit of work, not per attempt.
  idempotencyKey: messageId,
});

overagePolicy is yours to honour. reject means refuse the work once the allowance is gone - if you keep serving, the customer is getting something nobody is billing for and the setting is decorative. bill charges past the allowance up to maxOverageUnits.

Debiting is idempotent on idempotencyKey and nothing else. A retry without one double-charges a real customer.

Endpoints

GET /api/v1/application/plans

List this application's active plans

Scope plans:read  ·  Rate limit 60 requests / min per key

Lists every currently active plan on this application - the same catalog the "Subscribe" flow reads from - so you can render your own pricing instead of hardcoding it. Application-wide, not per-workspace; use subscription:read above to check which one plan a specific workspace is actually on.

Implementation

1. Prerequisite - an API key scoped to plans:read.

2. Send the request:

curl "https://connect.cosmoops.com/api/v1/application/plans" \
  -H "Authorization: Bearer YOUR_API_KEY_PLAINTEXT"

3. Read plans - archived plans are never included, so nothing here needs its own status check.

features is a list of { key, name, description }, joined against this application's own feature catalog - render name, gate on key. Note the asymmetry with subscription:read's plan.features, which stays a bare string[] of keys: that one is a gating contract your backend compares against, and a display label is neither stable nor comparable. This one is a catalogue, and a catalogue that renders campaign-module where it meant "Campaign module" is just wrong. name falls back to the key for a plan predating this application's feature catalog.

Errors

forbidden (403 - key missing plans:read), rate_limited (429 - same read-heavy generous limit as rbac:read/subscription:read).

Responses

Response body

GET /api/v1/application/addons/workspaces/{workspaceId}

Read remaining balance for every consumable add-on

Scope addons:read  ·  Rate limit 60 requests / min per key

The read half of addons:consume below: how much of each consumable add-on a workspace has left this cycle. Without it an application could debit an allowance on every request and had no way to show its own users what remained - subscription:read returns subscription.addons as a list of ids and stops there.

Implementation

1. Prerequisite - an API key scoped to addons:read. Separate from addons:consume on purpose, the same way drive:read is separate from drive:write: a key that only renders a usage meter should not also be able to spend the balance down.

2. Send the request:

curl "https://connect.cosmoops.com/api/v1/application/addons/workspaces/WORKSPACE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY_PLAINTEXT"

3. Render balance against includedPerCycle. There is deliberately no "used" field: under carryForward an unspent balance rolls into the next cycle, so balance can exceed includedPerCycle and included - balance would go negative. balance itself goes negative only when overagePolicy is "bill" - that is accrued overage, capped at maxOverageUnits.

4. resetsAt is the end of the current billing cycle, when balances are re-granted.

A workspace with no subscription, no consumable add-ons, or none selected returns an empty addons array - not an error, since your reaction to all three is the same. Unlike consuming, this is not gated on the subscription being active: a paused subscription still holds its balance, and hiding it while someone works out what they have left would be perverse.

Errors

forbidden (403 - key missing addons:read), rate_limited (429 - same read-heavy limit as subscription:read).

Parameters

Responses

Response body

POST /api/v1/application/addons/consume

Debit a consumable add-on's balance

Scope addons:consume  ·  Rate limit 60 requests / min per key

Debits units from a consumable add-on the workspace is subscribed to on this application (see PlanAddonConsumable) - the metered counterpart to the read-only endpoints above. Call it at whatever cadence your own usage happens (per request, per generation, per unit), not once per cycle.

Implementation

1. Prerequisite - an API key scoped to addons:consume, and the workspace must be actively subscribed to a plan whose selected add-ons include addonId.

2. Send the request - and send an Idempotency-Key with it. This matters more here than on any other endpoint in this reference: a retried consume without one debits the balance twice, and units cannot be un-spent.

curl -X POST https://connect.cosmoops.com/api/v1/application/addons/consume \
  -H "Authorization: Bearer YOUR_API_KEY_PLAINTEXT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID","addonId":"ADDON_ID","quantity":1,"description":"pdf-export"}'

3. Read balance - what remains after this call. overageUnits is how much of quantity went past the balance and will be billed on the next cycle; it is always 0 when the add-on's overagePolicy is "reject", because that policy fails the call outright rather than partially succeeding.

Errors

validation_error (400 - malformed body, or an add-on that isn't consumable/isn't selected on the workspace's plan, or an inactive subscription), forbidden (403 - key missing addons:consume), not_found (404 - unknown workspace or add-on), insufficient_balance (409 - not enough balance and overagePolicy is "reject"), rate_limited (429).

Request body

Responses

Response body

GET /api/v1/application/credit/balance

Read a workspace's prepaid credit

Scope credit:read  ·  Rate limit 120 requests / min per key

A workspace's prepaid credit with your application - a rupee balance the customer buys from Connect whenever they like (GST charged on the top-up, invoiced by Connect) and your application spends per use. Unlike a consumable add-on it does not reset each cycle, and it can be topped up mid-cycle and credited back.

Amounts are paise, pre-tax. spendable is what a consume may take right now: the balance plus any overdraft Connect granted your application (usually none). topUpPath is the Connect page that sells more - hand it to useConnect().openConnect() and the customer returns to you when they have paid. topUpAvailable is false when your program is switched off.

Errors

validation_error (400), forbidden (403 - key missing credit:read), not_found (404 - the workspace holds no credit with you and has not installed your application), rate_limited (429).

Parameters

Responses

Response body

GET /api/v1/application/credit/ledger

List a workspace's credit movements

Scope credit:read  ·  Rate limit 120 requests / min per key

Every movement of a workspace's credit with your application, newest first: topup (the customer bought credit), consume and refund (yours), adjustment (Connect support) and migration (a balance carried over from an older Connect product). amount is signed; balanceAfter is the balance once it applied. Page with cursor = the last page's nextCursor.

Parameters

Responses

Response body

POST /api/v1/application/credit/consume

Spend prepaid credit

Scope credit:write  ·  Rate limit 300 requests / min per key

Debits a workspace's prepaid credit for one unit of work - a call when it ends, a message when it is sent.

Implementation

1. Prerequisite - an API key scoped to credit:write, and a credit program for your application in Connect (set up by the Connect team: the top-up packs, your SAC code and GST rate).

2. Send idempotencyKey - it is required. Use your own id for the unit of work (the call id). It becomes the ledger entry's id, written in the same transaction as the balance, so a retry answers duplicate: true with the original entry and moves nothing - however long after. Reusing a key for a different amount is refused with idempotency_key_reused.

curl -X POST https://connect.cosmoops.com/api/v1/application/credit/consume \
  -H "Authorization: Bearer YOUR_API_KEY_PLAINTEXT" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID","amount":360,"idempotencyKey":"call_8f2a","description":"Call to +91 98xxx (4 min)","reference":"call_8f2a"}'

3. Credit never goes negative unless Connect granted you an overdraft. A consume larger than spendable is refused with insufficient_credit (409) and nothing moves; send the customer to topUpPath. Check spendable before work you cannot stop half-way.

Errors

validation_error (400), forbidden (403 - key missing credit:write), not_found (404), insufficient_credit (409), idempotency_key_reused (409), rate_limited (429).

Request body

Responses

Response body

POST /api/v1/application/credit/refund

Credit back an earlier consume

Scope credit:write  ·  Rate limit 300 requests / min per key

Returns part or all of one earlier consume to the balance - a call that dropped, a message the carrier never delivered. Name the consume by the idempotencyKey it was sent with (consumeIdempotencyKey); several credit-backs may follow one consume, but never more in total than it took. Idempotent on its own idempotencyKey, exactly like consume. A refund here moves credit, not money: the customer's card is never touched.

Errors

validation_error (400 - more than what remains of that consume), forbidden (403), not_found (404 - no consume under that key), idempotency_key_reused (409), rate_limited (429).

Request body

Responses

Response body