One billing period with its accrual lines

GET /api/v1/billing/periods/{id}

https://app.tanba-ooh.kz/api/v1/billing/periods/{id}

Scope read:billing.

Authentication

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

Scope: read:billing

Parameters

Name	In	Type	Required	Description	Example
`id`	path	string (uuid)	yes	Identifier of the billing period.	`0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10`

Responses

200 The period.

`application/json`

Name	Type	Required	Description	Example
`period`	object	yes	The billing period.
`period.id`	string (uuid)	yes	Identifier of the billing period.	`"0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10"`
`period.org_id`	string (uuid)	yes	Identifier of the organisation billed.	`"3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92"`
`period.org_name`	string		Name of the organisation billed.	`"Alma Outdoor LLP"`
`period.period_start`	string (date)	yes	First day of the period.	`"2026-09-01"`
`period.period_end`	string (date)	yes	Last day of the period.	`"2026-09-30"`
`period.status`	string	yes	Whether the period is still accruing. open, closed
`period.closed_at`	string \| null		When the period was closed; null while it is open.	`"2026-10-02T09:00:00+05:00"`
`period.total_kzt`	string	yes	Total of the period in tenge, as a decimal string.	`"1250000.00"`
`period.vat_kzt`	string	yes	VAT on the total in tenge, as a decimal string.	`"150000.00"`
`period.statements`	integer		Number of statements issued for the period.	`2`
`lines`	array of BillingLine	yes	The accrual lines of the period. A play line names the evidence tiers and the multiplier model behind it.
`lines[].id`	integer (int64)	yes	Identifier of the line; the evidence pack of a play line is asked for with it.	`4711`
`lines[].kind`	string	yes	What the line charges for. impression, approval_single, approval_prepaid, lab
`lines[].source_ref`	string	yes	The structure and the hours of a play line (`S-001 2026-10-05T10..2026-10-20T11`), the structure and the month of a late line (`S-001 late 2026-09`), or the approval number of a fee line.	`"S-001 2026-10-05T10..2026-10-20T11"`
`lines[].quantity`	string	yes	Billing units with three decimals. For a play line it is plays multiplied by the multiplier of the structure's format in the model (billing-v0 is 1.000 for every format, so units equal plays); for a fee line it is 1.	`"3739.000"`
`lines[].amount_kzt`	string	yes	The line amount in tenge, without VAT	`"1869.50"`
`lines[].vat_kzt`	string	yes	VAT on the line in tenge; 0.00 while the payee is not a VAT payer	`"0.00"`
`lines[].tiers`	array of string	yes	Evidence tiers that gave the plays of the line (`mtls`, `signed`, `attested`, `native`). Per structure, approval and hour only the tier with the most plays counts. Empty for a fee line.	`["mtls", "signed"]`
`lines[].model`	string	yes	Code of the multiplier model that turned plays into units; empty for a fee line.	`"billing-v0"`
`statements`	array of object	yes	Statements issued for the period.
`reported_not_billed`	object	yes	Plays reported in the period but outside the bill: tiers that are not in the billable set, and the hourly rows an operator imported from its own CMS (tier `import`, never billable). Per structure, approval and hour the larger figure counts.
`reported_not_billed.plays`	integer (int64)	yes	All plays reported and not billed in the month	`1900`
`reported_not_billed.by_tier`	array of object	yes	The same figure split by the tier it was reported on.
`reported_not_billed.by_tier[].tier`	string	yes	The reporting channel. mtls, signed, attested, native, import
`reported_not_billed.by_tier[].plays`	integer (int64)	yes	Plays reported on that tier and not billed	`1200`
`shortfalls`	array of BillingShortfall	yes	Closed months of this organisation for which the plays now on file are fewer than were billed. They are shown for the authority and never credited automatically.
`shortfalls[].month`	string	yes	The closed month	`"2026-09"`
`shortfalls[].structure`	string	yes	Structure code	`"S-001"`
`shortfalls[].approval_number`	string	yes	Approval the plays were counted against	`"TNB-2026-000001"`
`shortfalls[].billed_plays`	integer (int64)	yes	Plays in the evidence of the closed bill	`2000`
`shortfalls[].current_plays`	integer (int64)	yes	Billable plays on file now	`1500`

Example

{
  "period": {
    "id": "0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10",
    "org_id": "3a9d5e71-c4b2-4f08-b6d3-e8a1070c5f92",
    "org_name": "Alma Outdoor LLP",
    "period_start": "2026-09-01",
    "period_end": "2026-09-30",
    "status": "open",
    "closed_at": "2026-10-02T09:00:00+05:00",
    "total_kzt": "1250000.00",
    "vat_kzt": "150000.00",
    "statements": 2
  },
  "lines": [
    {
      "id": 4711,
      "kind": "impression",
      "source_ref": "S-001 2026-10-05T10..2026-10-20T11",
      "quantity": "3739.000",
      "amount_kzt": "1869.50",
      "vat_kzt": "0.00",
      "tiers": [
        "mtls",
        "signed"
      ],
      "model": "billing-v0"
    }
  ],
  "statements": [
    {}
  ],
  "reported_not_billed": {
    "plays": 1900,
    "by_tier": [
      {
        "tier": "import",
        "plays": 1200
      }
    ]
  },
  "shortfalls": [
    {
      "month": "2026-09",
      "structure": "S-001",
      "approval_number": "TNB-2026-000001",
      "billed_plays": 2000,
      "current_plays": 1500
    }
  ]
}

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`).
404	Nothing there, or not visible to the caller.
default	An error as a problem document.

Code samples

curl

curl 'https://app.tanba-ooh.kz/api/v1/billing/periods/0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Python

import requests

response = requests.get(
    "https://app.tanba-ooh.kz/api/v1/billing/periods/0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10",
    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/periods/0b1c3a52-6f0e-4c2e-9d3a-2f5d1e7a9c10", 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))
}