POST /apiv2/billing/limits

Create, change, switch off and switch on your own limits inside the credit limit set by Netts. The limits set by Netts cannot be changed with these endpoints. Part of postpaid billing.

Endpoints

Endpoint	Does
POST /apiv2/billing/limits	create your own limit
PUT /apiv2/billing/limits/{id}?scope=account	change its value
POST /apiv2/billing/limits/{id}/disable?scope=account	switch it off — it stops applying, nothing is deleted
POST /apiv2/billing/limits/{id}/enable?scope=account	switch it on again

{id} is the limit id from limits. scope=account is required for changes.

Request headers

Header	Required	Description
X-API-KEY	yes	API key with the limits.write permission
X-Real-IP	yes	An address from the key whitelist
Idempotency-Key	yes	a unique string, 8–128 characters, one per change
Content-Type	yes	application/json

Idempotency-Key makes a retry safe. Repeat a request with the same key and the same body — after a timeout, for example — and you get the original answer back; the change is not made twice. The same key with a different body is refused with 409 idempotency_conflict.

expectedRevision protects you from overwriting a change you have not seen. Send the revision you read last (0 when you create a limit). If the limit changed meanwhile, the request is refused with 409 revision_conflict — read limits again and retry.

Create a limit

Field	Type	Required	Description
productCode	string or null	no	energy_1h, energy_5m, bandwidth, activation, aml_check; null or omitted for your overall limit
period	string	yes	outstanding, day, week or order
value	string	yes	the amount, in the currency of the Netts limit, not higher than it
expectedRevision	integer	yes	0

You can have one limit of your own for each product and period. The currency is taken from the Netts limit — there is no currency field.

curl -s -X POST 'https://netts.io/apiv2/billing/limits' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-day' \
  -H 'Content-Type: application/json' \
  -d '{"productCode": "energy_5m", "period": "day", "value": "200", "expectedRevision": 0}'

{
  "success": true,
  "data": {
    "id": 5,
    "scope": "account",
    "origin": "client",
    "productCode": "energy_5m",
    "period": "day",
    "enabled": true,
    "limit": { "unit": "USD", "value": "200.000000" },
    "equivalent": { "unit": "TRX", "value": "604.514867" },
    "revision": 1,
    "fx": { "usdPerTrx": "0.33084276", "at": "2026-10-19T20:24:23.449930+00:00" },
    "fxStatus": "ok"
  },
  "timestamp": "2026-10-19T20:30:02+00:00"
}

The limit applies to the next order right away.

Change a limit

curl -s -X PUT 'https://netts.io/apiv2/billing/limits/5?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-300' \
  -H 'Content-Type: application/json' \
  -d '{"value": "300", "expectedRevision": 1}'

Field	Type	Required	Description
value	string	yes	the new amount, not higher than the Netts limit
expectedRevision	integer	yes	the current revision of the limit

The answer has the same format as above, with revision increased by one.

Switch a limit off or on

curl -s -X POST 'https://netts.io/apiv2/billing/limits/5/disable?scope=account' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Idempotency-Key: 6f1c2b8e-limit-5m-off' \
  -H 'Content-Type: application/json' \
  -d '{"expectedRevision": 2}'

The body has only expectedRevision. /enable works the same way. A switched-off limit stays in the list with "enabled": false and can be switched on later; your debt and charges are not affected.

What you cannot do

• Change or switch off a limit with "origin": "netts" or a key limit — 403 netts_limit_readonly, even to lower it.
• Set a value higher than the Netts limit — 422 above_account_limit.
• Create a second limit for the same product and period — 409 limit_exists; change the existing one instead.
• Create a limit before Netts has set the credit limit of your account — 409 no_account_limit.
• Switch on a limit whose currency differs from the current Netts limit — 422 unit_mismatch; set a new value first.

Errors

HTTP	code	Meaning
400	invalid_request, invalid_amount	a field is missing or has a wrong format
400	idempotency_key_required, invalid_idempotency_key	no Idempotency-Key, or not 8–128 characters
401	-1, -2	the key is missing or invalid, or the IP is not whitelisted — answered by the API gateway, see response format
403	forbidden	the key has no limits.write permission
403	postpaid_disabled	postpaid billing is paused: limits cannot be changed
403	netts_limit_readonly	the limit is set by Netts
404	not_found	no such limit on your account
409	revision_conflict, limit_exists, idempotency_conflict, no_account_limit	see above
422	above_account_limit, product_not_postpaid, unit_mismatch	value above the Netts limit, unknown product, currency of the Netts limit changed

All codes are listed in postpaid billing.