Prepaid approvals bought, used and left

GET /api/v1/billing/entitlements

https://app.tanba-ooh.kz/api/v1/billing/entitlements

Scope read:billing. The prepaid approval rate (7 000 tenge instead of 10 000) applies to a submission only while its billed organisation has a unit left: units bought minus the prepaid submissions that are submitted, in review or approved. A withdrawn or rejected submission returns its unit. The billed organisation is the operator of the structures, else the applicant. A caller sees its own organisation; the authority and the platform administrator see every organisation with a purchase or a prepaid submission, and the purchases recorded. A prepaid submission sent for review with no unit left is refused with the prepaid_balance problem (422) on POST /api/v1/submissions/{id}/submit.

Authentication

API key in the Authorization header, or a console session.

Scope: read:billing

Responses

200 Balances and the purchases recorded, newest first.

`application/json`

Name	Type	Required	Description	Example
`more`	boolean		Present and true when more than 200 purchases exist and the list is cut.	`true`
`items`	array of PrepaidBalance	yes	One balance per organisation.
`items[].org_id`	string (uuid)	yes	Identifier of the organisation billed.	`"3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92"`
`items[].org_name`	string	yes	Name of the organisation billed.	`"Alma Outdoor LLP"`
`items[].purchased`	integer (int64)	yes	Prepaid approvals bought.	`20`
`items[].used`	integer (int64)	yes	Prepaid submissions that are submitted, in review or approved.	`7`
`items[].balance`	integer (int64)	yes	Units left; a prepaid submission is accepted while this is at least 1.	`13`
`purchases`	array of PrepaidPurchase	yes	Purchases recorded for the visible organisations, newest first, up to 200.
`purchases[].id`	string (uuid)	yes	Identifier of the purchase.	`"9d2f6a30-18c4-4e7b-a1d5-62b0c7e3f814"`
`purchases[].org_id`	string (uuid)	yes	Organisation the units were bought for.	`"3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92"`
`purchases[].quantity`	integer	yes	Approvals bought.	`20`
`purchases[].paid_on`	string \| null (date)	yes	Day the payment was received; null when not stated.	`"2026-10-01"`
`purchases[].reference`	string	yes	Invoice or payment the purchase rests on; may be empty.	`"Invoice 17"`
`purchases[].recorded_at`	string (date-time)	yes	When the platform administrator recorded the purchase.	`"2026-10-02T09:00:00Z"`

Example

{
  "more": true,
  "items": [
    {
      "org_id": "3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92",
      "org_name": "Alma Outdoor LLP",
      "purchased": 20,
      "used": 7,
      "balance": 13
    }
  ],
  "purchases": [
    {
      "id": "9d2f6a30-18c4-4e7b-a1d5-62b0c7e3f814",
      "org_id": "3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92",
      "quantity": 20,
      "paid_on": "2026-10-01",
      "reference": "Invoice 17",
      "recorded_at": "2026-10-02T09:00:00Z"
    }
  ]
}

Errors

Errors are problem documents (application/problem+json) with a stable code.

Status	Meaning
401	No valid session or API key (`unauthenticated`, `session_expired`, `invalid_api_key`).
403	The role or the key's scope does not allow this (`forbidden`, `key_scope_denied`, `key_route_denied`).
default	An error as a problem document.

Code samples

curl

curl 'https://app.tanba-ooh.kz/api/v1/billing/entitlements' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://app.tanba-ooh.kz/api/v1/billing/entitlements",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
    },
)
print(response.status_code, response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://app.tanba-ooh.kz/api/v1/billing/entitlements", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}