API : AI quota : Buy top-up

Introduction

This request buys an AI_TOP_UP product for a customer. The amounts of the product are added to the customer's allowance for the current month only - they raise this month's limits and lapse when the month ends. Several top-ups can be bought in the same month; they stack.

Use Top-up products to get the list of products the customer may buy.

The purchase happens in this order:

The amounts are credited to this month's counter, so the customer can use them immediately. This is done first on purpose: an uninvoiced credit can be corrected, a charge without the credit cannot.
A locked line of type AI_TOP_UP is added to the customer's current invoice with the full product embedded, one unit, and a Danish description naming the amounts and the period. The line is skipped when the product's price is 0.
A reseller invoice line is created when the product has a wholesale price above 0.
The 80 % / 100 % warning thresholds are re-armed for the resources the top-up raised, so a later crossing warns again.
The purchase is written to the customer's change log.

The customer must have an AI product in effect, and the top-up must belong to that product's family (aiTopUp.product must be the master AI product the customer's product descends from) - otherwise the request is refused with 409.

Request

URL	https://api.telecomx.dk/ai/quota/topup/PRODUCT_ID
Method	POST
Access level	OWNER for the user's own customer, with write access to it. RESELLER, RESELLER_ADMIN or ADMIN, who may also name another customer with customer.
Param	PRODUCT_ID	Id of the AI_TOP_UP product to buy (24 hex-char string)
Query	customer	`[optional]` Id of the customer to buy for. Only honoured for RESELLER and up, and write access to the customer is checked. Defaults to the user's own customer.

The request has no body.

Query examples

https://api.telecomx.dk/ai/quota/topup/650000000000000000000420
https://api.telecomx.dk/ai/quota/topup/650000000000000000000420?customer=650000000000000000000101

Response

JSON object
success	Boolean	True on success.
month	String	The month the amounts were added to, `YYYY-MM` in Europe/Copenhagen.
product	Object	The product that was bought.
product._id	Id	Id of the product.
product.name	String	Product name.
product.price	Number	The customer price that was invoiced.
product.aiTopUp.sttSeconds	Number	Transcription seconds added.
product.aiTopUp.llmTokens	Number	Summary tokens added.
product.aiTopUp.ttsCharacters	Number	Text-to-speech characters added.
product.aiTopUp.product	Id	The master AI product this top-up applies to.
topUp	Object	The month's total top-up amounts after this purchase (including earlier purchases in the same month).
topUp.sttSeconds	Number	Transcription seconds added this month.
topUp.llmTokens	Number	Summary tokens added this month.
topUp.ttsCharacters	Number	Text-to-speech characters added this month.

Example

{
  "success": true,
  "month": "2026-09",
  "product": {
    "_id": "650000000000000000000420",
    "name": "AI top-up: 5 hours transcription",
    "price": 199.00,
    "aiTopUp": {
      "sttSeconds": 18000,
      "llmTokens": 0,
      "ttsCharacters": 0,
      "product": "650000000000000000000310"
    }
  },
  "topUp": { "sttSeconds": 18000, "llmTokens": 0, "ttsCharacters": 0 }
}

Errors

Error code	Message	Description
422	product	Product id is invalid
422	customer	Customer id is invalid
404	customer	Customer not found
404	product	Top-up product not found, or not one this customer may buy
409	aiProduct	The customer has no AI product - a top-up cannot be bought
409	aiTopUp	This top-up does not apply to the customer's AI product
409	aiTopUp	The top-up product adds nothing
403	access_denied	Insufficient access level, or no write access to the customer
500	internal_error	<Unspecified>

A failure while invoicing after the amounts were credited is logged to syslog as ai-topup: credited but failed to invoice with the product and customer ids, and the request fails - the invoice line must then be added by hand.

WIKI

Table of Contents