API reference

Billing

Plans, the rial wallet, top-ups, usage, invoices and tax details. Amounts in rials.

GET/v1/pricing

The public price list#

Plans, per-meter rials and the limits the platform enforces, from the dated price book. Cache-Control: public, max-age=300, with an ETag (If-None-Match gives 304). CORS: Access-Control-Allow-Origin * for GET. Pro is per developer seat (owner, admin, developer) per month, each seat's fee back as usage credit; a seat added mid-month pays the days left.

Credential: None

Response

200Pricing

effective_fromstring (date)required
currencystringrequired
one of IRR
vat_percentnumber
grace_hoursnumber
plansPublicPlan[]required
- idstringrequired
  one of hobby, pro, enterprise
- seat_fee_per_monthinteger
  rials per seat per month
- usage_creditinteger
  rials per seat per month
- per_seatboolean
  true for Pro
- max_seatsinteger | null
  1 for Hobby; null for Pro
- seat_rolesstring[]
  Pro: the roles that take a seat
- free_rolesstring[]
  Pro: the roles that do not
- prorationstring
  Pro: daily, a seat added mid-month pays the days left
  one of daily
- overageboolean
  false: the plan stops at its included amounts
- spend_budget_defaultinteger | null
  rials (1 toman = 10 rials)
- limitsPlanLimits
- customboolean
  enterprise: priced by contract
metersobject[]required
- meterstringrequired
- labelstring
- unitstringrequired
- label_fastring | null
- unit_fastring | null
- rialsintegerrequired
  per unit, rounded as an invoice's unit price
- includedobject

Errors

Status	Description
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/pricing"

GET/v1/billing

Plan, state and wallet#

Credential: An API key or a dashboard session
Roles: Any role

Response

200Billing

planstringrequired
one of hobby, pro
statestringrequired
grace_untilstring (date-time) | null
currencystringrequired
one of IRR
balanceintegerrequired
rials (1 toman = 10 rials)
periodstringrequired
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
usage_this_periodinteger
rials (1 toman = 10 rials)
seatsinteger
members that take a developer seat (owner, admin, developer)
seatobject
- rolesstring[]
- maxinteger | null
  1 on Hobby; null on Pro
- paid_this_periodinteger
  seats paid this month; removed and demoted ones stay paid to its end
- free_nowinteger
  paid seats no member uses: the next one added is free
- next_seatobject | null
  Pro: what one more seat costs now when none is free
usage_creditobject | null
Pro: the month's seats' credit
- totalinteger
  rials (1 toman = 10 rials)
- leftinteger
  rials (1 toman = 10 rials)
spendobject | null
- limitinteger
  rials (1 toman = 10 rials)
- pauseboolean
- usedinteger
  rials (1 toman = 10 rials)
burn_per_dayinteger
rials (1 toman = 10 rials)
days_leftinteger | null
plansobject
- proobject
  per seat
payment_methodsobject[]
the ways a top-up can be paid
- idstringrequired
  goes in a top-up's method
- labelstringrequired
  for people, e.g. card payment

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/prices

The price book#

Credential: An API key or a dashboard session
Roles: Any role

Response

200Prices

toman_per_usdnumber
vat_percentnumber
pricesPrice[]required
- meterstringrequired
- labelstring
- unitstringrequired
- label_fastring | null
  Persian
- unit_fastring | null
  Persian
- usdnumber
- rialsintegerrequired
  per unit
- includedobject

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/prices" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/usage

Usage and cost per meter for a month#

Database compute is sold by the compute-hour.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

periodstringquery
Jalali month; default this month
pattern ^\d{4}-\d{2}$

Response

200BillingUsage

periodstringrequired
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
metersMeterUsage[]required
- meterstringrequired
- labelstring
- unitstring
- label_fastring | null
  Persian
- unit_fastring | null
  Persian
- quantitynumber
- includednumber
- billablenumber
- amountintegerrequired
  rials (1 toman = 10 rials)
notestring

Errors

Status	Description
400	Bad request: `bad_period`
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/usage" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/usage/history

Usage over time, for charts#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

granularitystringquery
day (default): each day of a month up to today; month: each of the last months
one of day, month
periodstringquery
day: the Jalali month, default this one
pattern ^\d{4}-\d{2}$
monthsintegerquery
month: how many, 1-24, default 12
1–24
meterstringquery
meters to keep (comma list)

Response

200UsageHistory

granularitystringrequired
one of day, month
periodstring
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
metersobject[]required
- meterstringrequired
- labelstringrequired
- unitstringrequired
- label_fastring | null
- unit_fastring | null
pointsobject[]required
- atstringrequired
  a Tehran date (YYYY-MM-DD) or a Jalali month (YYYY-MM)
- totalintegerrequired
  rials (1 toman = 10 rials)
- metersobjectrequired

Errors

Status	Description
400	Bad request: `bad_param`, `bad_period`
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/usage/history" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/transactions

The wallet ledger (newest 200)#

Credential: An API key or a dashboard session
Roles: Any role

Response

200object

transactionsTransaction[]required
- idintegerrequired
- amountintegerrequired
  rials (1 toman = 10 rials)
- kindstringrequired
  one of topup, usage, plan_fee, vat, credit, refund, adjustment
- refstring | null
- memostring | null
- created_atstring (date-time)
- balanceinteger
  rials (1 toman = 10 rials)

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/transactions" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/payments

Top-up payments (newest 100)#

Masked card numbers are the payer's: billing roles only.

Credential: An API key or a dashboard session
Roles: owner, admin, billing

Response

200object

paymentsPayment[]required
- idstring (uuid)required
- methodstring
  the payment method's label
- amountintegerrequired
  rials (1 toman = 10 rials)
- statusstringrequired
  one of created, paid, failed
- ref_idstring | null
- card_panstring | null
  masked
- errorstring | null
  one of cancelled, the payment was not completed
- created_atstring (date-time)
- verified_atstring (date-time) | null

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/payments" \
  -H "Authorization: Bearer $KEY"

POST/v1/billing/topups

Start a top-up#

Returns a payment page; the wallet is credited when the provider confirms.

Credential: An API key or a dashboard session
Roles: owner, admin, billing

Request body`application/json`

amountintegerrequired
rials
100000–2000000000
methodstring
the id of one of payment_methods in GET /v1/billing; default the first

Response

200TopupCreated

paymentstring (uuid)required
amountinteger
rials (1 toman = 10 rials)
methodstring
method_labelstring
pay_urlstringrequired

Errors

Status	Description
400	Bad request: `bad_amount`, `bad_payment_method`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
500	`internal`: an unexpected failure
502	Upstream failure: `psp`

Example

curl -X POST "https://api.ibel.ai/v1/billing/topups" \
  -H "Authorization: Bearer $KEY" \
  -d '{"amount":100000}'

GET/v1/billing/callback/{method}

Payment page redirect (not for API clients)#

Verifies the payment, credits the wallet and redirects to the dashboard.

Credential: None

Parameters

methodstringpathrequired
the payment method's id
Authoritystringquery
the payment's reference

Response

302Redirect to the dashboard's billing page with ?payment=paid|failed&id=<payment>

Errors

Status	Description
500	`internal`: an unexpected failure

Example

Request

curl "https://api.ibel.ai/v1/billing/callback/card"

PUT/v1/billing/spend

Set the Pro spend budget#

Credential: An API key or a dashboard session
Roles: owner, admin, billing
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Request body`application/json`

limitinteger | null
at least 0
pauseboolean

Response

200Spend

limitinteger | null
at least 0
pauseboolean

Errors

Status	Description
400	Bad request: `bad_limit`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/billing/spend" \
  -H "Authorization: Bearer $KEY" \
  -d '{"limit":0,"pause":true}'

POST/v1/billing/plan

Change plan#

Pro: the month's fee for every seat, plus VAT, now. Hobby: one seat at most; no refund.

Credential: An API key or a dashboard session
Roles: owner, admin, billing
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Request body`application/json`

planstringrequired
one of pro, hobby

Response

200object

planstringrequired

Errors

Status	Description
400	Bad request: `bad_plan`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
402	Payment required: `insufficient_balance`
403	Not allowed: `forbidden`, `step_up_required`
409	Conflict: `seat_limit`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/billing/plan" \
  -H "Authorization: Bearer $KEY" \
  -d '{"plan":"pro"}'

GET/v1/billing/tax-details

The buyer's tax details#

Credential: An API key or a dashboard session
Roles: owner, admin, billing

Response

200object

tax_detailsTaxDetails | nullrequired
- buyer_typestringrequired
  one of person, company
- legal_namestringrequired
  up to 200 characters
- national_idstringrequired
- economic_codestring | null
- postal_codestring | null
  pattern ^\d{10}$
- addressstring | null
  up to 500 characters
- updated_atstring (date-time)

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/tax-details" \
  -H "Authorization: Bearer $KEY"

PUT/v1/billing/tax-details

Set the buyer's tax details#

Credential: An API key or a dashboard session
Roles: owner, admin, billing
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Request body`application/json`

buyer_typestringrequired
one of person, company
legal_namestringrequired
up to 200 characters
national_idstringrequired
economic_codestring | null
postal_codestring | null
pattern ^\d{10}$
addressstring | null
up to 500 characters
updated_atstring (date-time)

Response

200object

savedboolean

Errors

Status	Description
400	Bad request: `bad_type`, `bad_name`, `bad_national_id`, `bad_economic_code`, `bad_postal_code`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/billing/tax-details" \
  -H "Authorization: Bearer $KEY" \
  -d '{"buyer_type":"person","legal_name":"…","national_id":"…"}'

GET/v1/billing/invoices

Issued invoices#

Credential: An API key or a dashboard session
Roles: Any role

Response

200object

invoicesInvoiceSummary[]required
- numberstringrequired
  pattern ^\d{4}-\d{6}$
- periodstringrequired
  a Jalali month, YYYY-MM, e.g. 1405-08
  pattern ^\d{4}-\d{2}$
- issued_atstring (date-time)
- netinteger
  rials (1 toman = 10 rials)
- vatinteger
  rials (1 toman = 10 rials)
- totalintegerrequired
  rials (1 toman = 10 rials)

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/invoices" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/invoices/{number}

An invoice, or `preview` for this month so far#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

numberstringpathrequired
invoice number, e.g. 1405-000001, or preview
periodstringquery
preview only: Jalali month
pattern ^\d{4}-\d{2}$

Response

200Invoice

numberstring | nullrequired
draftbooleanrequired
periodstringrequired
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
issued_atstring (date-time) | null
linesInvoiceLine[]required
- kindstringrequired
  one of usage, discount, plan
- meterstring
- descriptionstringrequired
- description_fastring
  Persian (not on invoices issued before 4 Nov 2026)
- quantitynumber
  plan lines: seats
- unitstring
  plan lines: seat-month (the month's seats) or seat (a seat added in the month)
- unit_fastring
  Persian
- unit_priceinteger
  rials (1 toman = 10 rials)
- amountintegerrequired
  rials (1 toman = 10 rials)
- credit_totalinteger
  discount line on Pro: the month's usage credit from its seats, rials
netintegerrequired
rials (1 toman = 10 rials)
vatintegerrequired
rials (1 toman = 10 rials)
totalintegerrequired
rials (1 toman = 10 rials)
statementobject
- fromstring (date-time)
- tostring (date-time)
- openinginteger
  rials (1 toman = 10 rials)
- topupsinteger
  rials (1 toman = 10 rials)
- creditsinteger
  rials (1 toman = 10 rials)
- chargesinteger
  rials (1 toman = 10 rials)
- closinginteger
  rials (1 toman = 10 rials)
buyerobject | null
tax details as at issue; for viewer and developer roles only buyer_type and legal_name
sellerobject
- namestring
- economic_codestring
- national_idstring
- addressstring

Errors

Status	Description
400	Bad request: `bad_period`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/billing/invoices/1405-000001" \
  -H "Authorization: Bearer $KEY"

The public price list#

Response

Errors

Example

Plan, state and wallet#

Response

Errors

Example

The price book#

Response

Errors

Example

Usage and cost per meter for a month#

Parameters

Response

Errors

Example

Usage over time, for charts#

Parameters

Response

Errors

Example

The wallet ledger (newest 200)#

Response

Errors

Example

Top-up payments (newest 100)#

Response

Errors

Example

Start a top-up#

Request bodyapplication/json

Response

Errors

Example

Payment page redirect (not for API clients)#

Parameters

Response

Errors

Example

Set the Pro spend budget#

Request bodyapplication/json

Response

Errors

Example

Change plan#

Request bodyapplication/json

Response

Errors

Example

The buyer's tax details#

Response

Errors

Example

Set the buyer's tax details#

Request bodyapplication/json

Response

Errors

Example

Issued invoices#

Response

Errors

Example

An invoice, or preview for this month so far#

Parameters

Response

Errors

Example

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

An invoice, or `preview` for this month so far#