# billing

 14 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/billing/

14 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​workspaces/​{ws}/​billing`](#get-v1-workspaces-ws-billing) | Invoices and acts in tenge: your company details, the seller, the documents (admins; MOCK billing) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​billing/​changes`](#get-v1-workspaces-ws-billing-changes) | Why did my bill change: this month so far against the same days of last month, by meter, app and automation (MOCK billing) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​billing/​documents`](#post-v1-workspaces-ws-billing-documents) | Issue an invoice or an act for a month: next number, frozen lines, VAT and customer (admins) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​billing/​documents/​{documentId}`](#get-v1-workspaces-ws-billing-documents-documentid) | One invoice or act, as issued (admins) |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​billing/​documents/​{documentId}/​paid`](#put-v1-workspaces-ws-billing-documents-documentid-paid) | Mark an invoice paid by hand: a date and a bank or Kaspi reference (admins) |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​billing/​documents/​{documentId}/​paid`](#delete-v1-workspaces-ws-billing-documents-documentid-paid) | Undo a paid mark made by mistake (admins) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​billing/​documents/​{documentId}/​void`](#post-v1-workspaces-ws-billing-documents-documentid-void) | Void a document with a reason. Its number stays used (admins) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​billing/​price-tags`](#get-v1-workspaces-ws-billing-price-tags) | What each app and automation you can open uses this month, at add-on list prices (MOCK billing) |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​billing/​profile`](#put-v1-workspaces-ws-billing-profile) | Set the company details printed on invoices and acts: name, BIN or IIN, address |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​billing/​quote`](#get-v1-workspaces-ws-billing-quote) | What an invoice or an act for a month would say, before it is issued |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​billing/​quote`](#post-v1-workspaces-ws-billing-quote) | Before switching a schedule on: how many runs it takes and what that does to the month (read-only) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​budgets`](#get-v1-workspaces-ws-budgets) | Budgets under the workspace cap: admins see all of them, a member sees the ones set on them |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​budgets`](#put-v1-workspaces-ws-budgets) | Set the budget on an app, automation, agent token or member (admins; creates or changes it) |
| [[DELETE]] | [`/​v1/​workspaces/​{ws}/​budgets/​{budgetId}`](#delete-v1-workspaces-ws-budgets-budgetid) | Remove a budget (admins) |

## Reference

### [[GET]] `/v1/workspaces/{ws}/billing`

Invoices and acts in tenge: your company details, the seller, the documents (admins; MOCK billing).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member (details and documents: admin)

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `profile` | object or null | yes |  |
| `profile.legalName` | string | yes | 1 to 200 characters |
| `profile.binIin` | string | yes |  |
| `profile.address` | string | yes | 1 to 300 characters |
| `profile.email` | string (email) or null | yes | up to 200 characters |
| `profile.contractRef` | string or null | yes | 1 to 160 characters |
| `profile.vatPayer` | boolean | yes |  |
| `profile.language` | "en" · "ru" · "kk" | yes |  |
| `profile.updatedAt` | string (date-time) | yes |  |
| `seller` | object | yes |  |
| `seller.configured` | boolean | yes |  |
| `seller.legalName` | string or null | yes |  |
| `seller.vat` | object | yes |  |
| `seller.vatChecked` | boolean | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `currency` | "KZT" | yes |  |
| `workspaceCurrency` | "EUR" · "USD" · "KZT" | yes |  |
| `canEdit` | boolean | yes |  |
| `newestInvoicePeriod` | string | yes |  |
| `newestActPeriod` | string | yes |  |
| `oldestPeriod` | string | yes |  |
| `documents` | object[] | yes |  |
| `documents[].id` | string | yes | at least 1 characters |
| `documents[].kind` | "invoice" · "act" | yes |  |
| `documents[].number` | string | yes | at least 1 characters |
| `documents[].period` | string | yes |  |
| `documents[].issuedOn` | string (date) | yes |  |
| `documents[].status` | "issued" · "paid" · "void" | yes |  |
| `documents[].relatedNumber` | string or null | yes |  |

…and 5 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/billing/changes`

Why did my bill change: this month so far against the same days of last month, by meter, app and automation (MOCK billing).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `limit` | query | integer |  | 1 to 50. default 8 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `currency` | "EUR" · "USD" · "KZT" | yes |  |
| `window` | object | yes |  |
| `window.thisStart` | string (date-time) | yes |  |
| `window.thisEnd` | string (date-time) | yes |  |
| `window.lastStart` | string (date-time) | yes |  |
| `window.lastEnd` | string (date-time) | yes |  |
| `window.days` | integer | yes | 1 to 31 |
| `bill` | object or null | yes |  |
| `bill.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `bill.last` | object | yes |  |
| `bill.now` | object | yes |  |
| `bill.delta` | object | yes |  |
| `bill.causes` | object[] | yes |  |
| `bill.unchanged` | boolean | yes |  |
| `units` | object[] | yes |  |
| `units[].unit` | "runs" · "ai_credits" · "requests" | yes |  |
| `units[].now` | number | yes | at least 0 |
| `units[].before` | number | yes | at least 0 |
| `units[].lastMonth` | number | yes | at least 0 |
| `units[].change` | number | yes |  |
| `units[].changePct` | number or null | yes |  |
| `units[].basis` | "counted" · "lower_bound" · "builds_only" | yes |  |
| `movers` | object[] | yes |  |
| `movers[].kind` | "app" · "automation" | yes |  |
| `movers[].id` | string | yes | at least 1 characters |
| `movers[].name` | string | yes | at least 1 characters |
| `movers[].appId` | string or null | yes |  |
| `movers[].unit` | "runs" · "ai_credits" | yes |  |
| `movers[].now` | number | yes | at least 0 |

…and 7 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/billing/documents`

Issue an invoice or an act for a month: next number, frozen lines, VAT and customer (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `kind` | "invoice" · "act" | yes |  |
| `period` | string | yes |  |
| `language` | "en" · "ru" · "kk" |  |  |
| `idempotencyKey` | string |  | 8 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `workspaceId` | string | yes | at least 1 characters |
| `kind` | "invoice" · "act" | yes |  |
| `number` | string | yes | at least 1 characters |
| `seq` | integer | yes | at least 1 |
| `year` | integer | yes | at least 2000 |
| `period` | string | yes |  |
| `periodStart` | string (date) | yes |  |
| `periodEnd` | string (date) | yes |  |
| `issuedOn` | string (date) | yes |  |
| `issuedAt` | string (date-time) | yes |  |
| `currency` | "KZT" | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `lines` | object[] | yes | up to 40 items |
| `lines[].kind` | "plan" · "add_on" | yes |  |
| `lines[].ref` | string | yes | 1 to 40 characters |
| `lines[].qty` | integer | yes | 1 to 100000 |
| `lines[].unitMinor` | integer | yes | 0 to 1000000000 |
| `lines[].amountMinor` | integer | yes | 0 to 1000000000 |
| `vat` | object | yes |  |
| `vat.mode` | "none" · "excluded" · "included" | yes |  |
| `vat.rateBp` | integer | yes | 0 to 5000 |
| `totals` | object | yes |  |
| `totals.netMinor` | integer | yes | 0 to 1000000000 |
| `totals.vatMinor` | integer | yes | 0 to 1000000000 |
| `totals.grossMinor` | integer | yes | 0 to 2147483647 |
| `customer` | object | yes |  |
| `customer.legalName` | string | yes | 1 to 200 characters |
| `customer.binIin` | string | yes |  |
| `customer.address` | string | yes | 1 to 300 characters |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/billing/documents/{documentId}`

One invoice or act, as issued (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `documentId` | path | string | yes | 1 to 64 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `workspaceId` | string | yes | at least 1 characters |
| `kind` | "invoice" · "act" | yes |  |
| `number` | string | yes | at least 1 characters |
| `seq` | integer | yes | at least 1 |
| `year` | integer | yes | at least 2000 |
| `period` | string | yes |  |
| `periodStart` | string (date) | yes |  |
| `periodEnd` | string (date) | yes |  |
| `issuedOn` | string (date) | yes |  |
| `issuedAt` | string (date-time) | yes |  |
| `currency` | "KZT" | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `lines` | object[] | yes | up to 40 items |
| `lines[].kind` | "plan" · "add_on" | yes |  |
| `lines[].ref` | string | yes | 1 to 40 characters |
| `lines[].qty` | integer | yes | 1 to 100000 |
| `lines[].unitMinor` | integer | yes | 0 to 1000000000 |
| `lines[].amountMinor` | integer | yes | 0 to 1000000000 |
| `vat` | object | yes |  |
| `vat.mode` | "none" · "excluded" · "included" | yes |  |
| `vat.rateBp` | integer | yes | 0 to 5000 |
| `totals` | object | yes |  |
| `totals.netMinor` | integer | yes | 0 to 1000000000 |
| `totals.vatMinor` | integer | yes | 0 to 1000000000 |
| `totals.grossMinor` | integer | yes | 0 to 2147483647 |
| `customer` | object | yes |  |
| `customer.legalName` | string | yes | 1 to 200 characters |
| `customer.binIin` | string | yes |  |
| `customer.address` | string | yes | 1 to 300 characters |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PUT]] `/v1/workspaces/{ws}/billing/documents/{documentId}/paid`

Mark an invoice paid by hand: a date and a bank or Kaspi reference (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `documentId` | path | string | yes | 1 to 64 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `paidOn` | string (date) | yes |  |
| `reference` | string or null |  | 1 to 120 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `workspaceId` | string | yes | at least 1 characters |
| `kind` | "invoice" · "act" | yes |  |
| `number` | string | yes | at least 1 characters |
| `seq` | integer | yes | at least 1 |
| `year` | integer | yes | at least 2000 |
| `period` | string | yes |  |
| `periodStart` | string (date) | yes |  |
| `periodEnd` | string (date) | yes |  |
| `issuedOn` | string (date) | yes |  |
| `issuedAt` | string (date-time) | yes |  |
| `currency` | "KZT" | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `lines` | object[] | yes | up to 40 items |
| `lines[].kind` | "plan" · "add_on" | yes |  |
| `lines[].ref` | string | yes | 1 to 40 characters |
| `lines[].qty` | integer | yes | 1 to 100000 |
| `lines[].unitMinor` | integer | yes | 0 to 1000000000 |
| `lines[].amountMinor` | integer | yes | 0 to 1000000000 |
| `vat` | object | yes |  |
| `vat.mode` | "none" · "excluded" · "included" | yes |  |
| `vat.rateBp` | integer | yes | 0 to 5000 |
| `totals` | object | yes |  |
| `totals.netMinor` | integer | yes | 0 to 1000000000 |
| `totals.vatMinor` | integer | yes | 0 to 1000000000 |
| `totals.grossMinor` | integer | yes | 0 to 2147483647 |
| `customer` | object | yes |  |
| `customer.legalName` | string | yes | 1 to 200 characters |
| `customer.binIin` | string | yes |  |
| `customer.address` | string | yes | 1 to 300 characters |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/workspaces/{ws}/billing/documents/{documentId}/paid`

Undo a paid mark made by mistake (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `documentId` | path | string | yes | 1 to 64 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `workspaceId` | string | yes | at least 1 characters |
| `kind` | "invoice" · "act" | yes |  |
| `number` | string | yes | at least 1 characters |
| `seq` | integer | yes | at least 1 |
| `year` | integer | yes | at least 2000 |
| `period` | string | yes |  |
| `periodStart` | string (date) | yes |  |
| `periodEnd` | string (date) | yes |  |
| `issuedOn` | string (date) | yes |  |
| `issuedAt` | string (date-time) | yes |  |
| `currency` | "KZT" | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `lines` | object[] | yes | up to 40 items |
| `lines[].kind` | "plan" · "add_on" | yes |  |
| `lines[].ref` | string | yes | 1 to 40 characters |
| `lines[].qty` | integer | yes | 1 to 100000 |
| `lines[].unitMinor` | integer | yes | 0 to 1000000000 |
| `lines[].amountMinor` | integer | yes | 0 to 1000000000 |
| `vat` | object | yes |  |
| `vat.mode` | "none" · "excluded" · "included" | yes |  |
| `vat.rateBp` | integer | yes | 0 to 5000 |
| `totals` | object | yes |  |
| `totals.netMinor` | integer | yes | 0 to 1000000000 |
| `totals.vatMinor` | integer | yes | 0 to 1000000000 |
| `totals.grossMinor` | integer | yes | 0 to 2147483647 |
| `customer` | object | yes |  |
| `customer.legalName` | string | yes | 1 to 200 characters |
| `customer.binIin` | string | yes |  |
| `customer.address` | string | yes | 1 to 300 characters |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/billing/documents/{documentId}/void`

Void a document with a reason. Its number stays used (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `documentId` | path | string | yes | 1 to 64 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `reason` | string | yes | 1 to 200 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `workspaceId` | string | yes | at least 1 characters |
| `kind` | "invoice" · "act" | yes |  |
| `number` | string | yes | at least 1 characters |
| `seq` | integer | yes | at least 1 |
| `year` | integer | yes | at least 2000 |
| `period` | string | yes |  |
| `periodStart` | string (date) | yes |  |
| `periodEnd` | string (date) | yes |  |
| `issuedOn` | string (date) | yes |  |
| `issuedAt` | string (date-time) | yes |  |
| `currency` | "KZT" | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `lines` | object[] | yes | up to 40 items |
| `lines[].kind` | "plan" · "add_on" | yes |  |
| `lines[].ref` | string | yes | 1 to 40 characters |
| `lines[].qty` | integer | yes | 1 to 100000 |
| `lines[].unitMinor` | integer | yes | 0 to 1000000000 |
| `lines[].amountMinor` | integer | yes | 0 to 1000000000 |
| `vat` | object | yes |  |
| `vat.mode` | "none" · "excluded" · "included" | yes |  |
| `vat.rateBp` | integer | yes | 0 to 5000 |
| `totals` | object | yes |  |
| `totals.netMinor` | integer | yes | 0 to 1000000000 |
| `totals.vatMinor` | integer | yes | 0 to 1000000000 |
| `totals.grossMinor` | integer | yes | 0 to 2147483647 |
| `customer` | object | yes |  |
| `customer.legalName` | string | yes | 1 to 200 characters |
| `customer.binIin` | string | yes |  |
| `customer.address` | string | yes | 1 to 300 characters |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/billing/price-tags`

What each app and automation you can open uses this month, at add-on list prices (MOCK billing).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `currency` | "EUR" · "USD" · "KZT" | yes |  |
| `period` | object | yes |  |
| `period.start` | string (date-time) | yes |  |
| `period.end` | string (date-time) | yes |  |
| `period.day` | integer | yes | 1 to 31 |
| `period.daysInPeriod` | integer | yes | 28 to 31 |
| `runs` | object | yes |  |
| `runs.allowance` | number | yes | at least 0 |
| `runs.used` | number | yes | at least 0 |
| `runs.pct` | number or null | yes | 0 to 1000 |
| `runs.inside` | boolean | yes |  |
| `runs.perThousand` | object | yes |  |
| `apps` | object[] | yes |  |
| `apps[].kind` | "app" · "automation" | yes |  |
| `apps[].id` | string | yes | at least 1 characters |
| `apps[].name` | string | yes | at least 1 characters |
| `apps[].appId` | string or null | yes |  |
| `apps[].runs` | number | yes | at least 0 |
| `apps[].aiCredits` | number or null | yes | at least 0 |
| `apps[].runsShare` | number or null | yes | at least 0 |
| `apps[].listValue` | object | yes |  |
| `apps[].projectedRuns` | number or null | yes | at least 0 |
| `apps[].projection` | "schedule" · "pace" · null or null | yes |  |
| `apps[].projectedListValue` | object or null | yes |  |
| `automations` | object[] | yes |  |
| `automations[].kind` | "app" · "automation" | yes |  |
| `automations[].id` | string | yes | at least 1 characters |
| `automations[].name` | string | yes | at least 1 characters |
| `automations[].appId` | string or null | yes |  |

…and 11 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PUT]] `/v1/workspaces/{ws}/billing/profile`

Set the company details printed on invoices and acts: name, BIN or IIN, address.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `legalName` | string | yes | 1 to 200 characters |
| `binIin` | string | yes |  |
| `address` | string | yes | 1 to 300 characters |
| `email` | string (email) or null | yes | up to 200 characters |
| `contractRef` | string or null | yes | 1 to 160 characters |
| `vatPayer` | boolean | yes |  |
| `language` | "en" · "ru" · "kk" | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `profile` | object or null | yes |  |
| `profile.legalName` | string | yes | 1 to 200 characters |
| `profile.binIin` | string | yes |  |
| `profile.address` | string | yes | 1 to 300 characters |
| `profile.email` | string (email) or null | yes | up to 200 characters |
| `profile.contractRef` | string or null | yes | 1 to 160 characters |
| `profile.vatPayer` | boolean | yes |  |
| `profile.language` | "en" · "ru" · "kk" | yes |  |
| `profile.updatedAt` | string (date-time) | yes |  |
| `seller` | object | yes |  |
| `seller.configured` | boolean | yes |  |
| `seller.legalName` | string or null | yes |  |
| `seller.vat` | object | yes |  |
| `seller.vatChecked` | boolean | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `currency` | "KZT" | yes |  |
| `workspaceCurrency` | "EUR" · "USD" · "KZT" | yes |  |
| `canEdit` | boolean | yes |  |
| `newestInvoicePeriod` | string | yes |  |
| `newestActPeriod` | string | yes |  |
| `oldestPeriod` | string | yes |  |
| `documents` | object[] | yes |  |
| `documents[].id` | string | yes | at least 1 characters |
| `documents[].kind` | "invoice" · "act" | yes |  |
| `documents[].number` | string | yes | at least 1 characters |
| `documents[].period` | string | yes |  |
| `documents[].issuedOn` | string (date) | yes |  |
| `documents[].status` | "issued" · "paid" · "void" | yes |  |
| `documents[].relatedNumber` | string or null | yes |  |

…and 5 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/billing/quote`

What an invoice or an act for a month would say, before it is issued.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `kind` | query | "invoice" · "act" | yes |  |
| `period` | query | string | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `kind` | "invoice" · "act" | yes |  |
| `period` | string | yes |  |
| `periodStart` | string (date) | yes |  |
| `periodEnd` | string (date) | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `lines` | object[] | yes |  |
| `lines[].kind` | "plan" · "add_on" | yes |  |
| `lines[].ref` | string | yes | 1 to 40 characters |
| `lines[].qty` | integer | yes | 1 to 100000 |
| `lines[].unitMinor` | integer | yes | 0 to 1000000000 |
| `lines[].amountMinor` | integer | yes | 0 to 1000000000 |
| `vat` | object | yes |  |
| `vat.mode` | "none" · "excluded" · "included" | yes |  |
| `vat.rateBp` | integer | yes | 0 to 5000 |
| `totals` | object | yes |  |
| `totals.netMinor` | integer | yes | 0 to 1000000000 |
| `totals.vatMinor` | integer | yes | 0 to 1000000000 |
| `totals.grossMinor` | integer | yes | 0 to 2147483647 |
| `usage` | object[] or null | yes |  |
| `usage[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `usage[].used` | number or null | yes | at least 0 |
| `usage[].allowance` | number | yes | at least 0 |
| `usage[].estimate` | boolean | yes |  |
| `relatedNumber` | string or null | yes |  |
| `problem` | object or null | yes |  |
| `problem.code` | "bad_period" · "before_workspace" · "too_old" · "too_far_ahead" · "period_not_finished" · "contract_plan" · "nothing_to_invoice" | yes |  |
| `problem.message` | string | yes |  |
| `problem.hint` | string | yes |  |
| `preview` | boolean | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/billing/quote`

Before switching a schedule on: how many runs it takes and what that does to the month (read-only).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `cron` | string |  | 1 to 120 characters |
| `timezone` | string |  | 1 to 64 characters |
| `perDay` | number |  | 0 to 100000000 |
| `appId` | string |  | 1 to 128 characters |
| `automationId` | string |  | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `basis` | "schedule" · "rate" | yes |  |
| `cron` | string or null | yes |  |
| `timezone` | string or null | yes |  |
| `periodRuns` | integer | yes | at least 0 |
| `remainingRuns` | integer | yes | at least 0 |
| `replacedRuns` | integer | yes | at least 0 |
| `perDay` | number | yes | at least 0 |
| `allowance` | number or null | yes | at least 0 |
| `used` | number or null | yes | at least 0 |
| `after` | number or null | yes | at least 0 |
| `pctAfter` | number or null | yes | 0 to 1000 |
| `shareOfAllowance` | number or null | yes | at least 0 |
| `verdict` | "fits" · "near" · "passes_allowance" · "refused" · "unknown" | yes |  |
| `extra` | object or null | yes |  |
| `extra.runs` | number | yes | at least 0 |
| `extra.steps` | integer | yes | at least 1 |
| `extra.monthly` | object | yes |  |
| `extra.canBuy` | boolean | yes |  |
| `listValue` | object | yes |  |
| `listValue.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `listValue.minor` | number | yes |  |
| `budgets` | object[] | yes |  |
| `budgets[].id` | string | yes | at least 1 characters |
| `budgets[].scope` | "app" · "automation" · "member" · "agent_token" | yes |  |
| `budgets[].scopeName` | string or null | yes |  |
| `budgets[].mode` | "soft" · "hard" | yes |  |
| `budgets[].limit` | integer | yes | at least 0 |
| `budgets[].used` | number | yes | at least 0 |
| `budgets[].after` | number | yes | at least 0 |
| `budgets[].pctAfter` | number | yes | 0 to 1000 |

…and 5 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/budgets`

Budgets under the workspace cap: admins see all of them, a member sees the ones set on them.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `period` | object | yes |  |
| `period.start` | string (date-time) | yes |  |
| `period.end` | string (date-time) | yes |  |
| `budgets` | object[] | yes |  |
| `budgets[].id` | string | yes | at least 1 characters |
| `budgets[].scope` | "app" · "automation" · "member" · "agent_token" | yes |  |
| `budgets[].scopeId` | string | yes | at least 1 characters |
| `budgets[].scopeName` | string or null | yes |  |
| `budgets[].meter` | "runs" · "ai_credits" | yes |  |
| `budgets[].limit` | integer | yes | at least 0 |
| `budgets[].mode` | "soft" · "hard" | yes |  |
| `budgets[].alerts` | 50 or 75 or 90 or 100[] | yes |  |
| `budgets[].coverage` | "enforced" · "tracked" | yes |  |
| `budgets[].used` | number or null | yes | at least 0 |
| `budgets[].pct` | number or null | yes | 0 to 1000 |
| `budgets[].state` | "ok" · "near" · "reached" · null or null | yes |  |
| `budgets[].alerted` | 50 or 75 or 90 or 100 or any or null | yes |  |
| `budgets[].blocking` | boolean | yes |  |
| `budgets[].updatedAt` | string (date-time) | yes |  |
| `budgets[].updatedByName` | string or null | yes |  |
| `cells` | object[] | yes |  |
| `cells[].scope` | "app" · "automation" · "member" · "agent_token" | yes |  |
| `cells[].meter` | "runs" · "ai_credits" | yes |  |
| `cells[].coverage` | "enforced" · "tracked" | yes |  |
| `cells[].stops` | "run_start" · "build_start" · "nothing_yet" | yes |  |
| `targets` | object[] | yes |  |
| `targets[].scope` | "app" · "automation" · "member" · "agent_token" | yes |  |
| `targets[].id` | string | yes | at least 1 characters |
| `targets[].name` | string | yes | at least 1 characters |

…and 4 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PUT]] `/v1/workspaces/{ws}/budgets`

Set the budget on an app, automation, agent token or member (admins; creates or changes it).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `scope` | "app" · "automation" · "member" · "agent_token" | yes |  |
| `scopeId` | string | yes | 1 to 128 characters |
| `meter` | "runs" · "ai_credits" | yes |  |
| `limit` | integer | yes | 0 to 1000000000 |
| `mode` | "soft" · "hard" | yes |  |
| `alerts` | 50 or 75 or 90 or 100[] |  | up to 4 items |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `scope` | "app" · "automation" · "member" · "agent_token" | yes |  |
| `scopeId` | string | yes | at least 1 characters |
| `scopeName` | string or null | yes |  |
| `meter` | "runs" · "ai_credits" | yes |  |
| `limit` | integer | yes | at least 0 |
| `mode` | "soft" · "hard" | yes |  |
| `alerts` | 50 or 75 or 90 or 100[] | yes |  |
| `coverage` | "enforced" · "tracked" | yes |  |
| `used` | number or null | yes | at least 0 |
| `pct` | number or null | yes | 0 to 1000 |
| `state` | "ok" · "near" · "reached" · null or null | yes |  |
| `alerted` | 50 or 75 or 90 or 100 or any or null | yes |  |
| `blocking` | boolean | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `updatedByName` | string or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/workspaces/{ws}/budgets/{budgetId}`

Remove a budget (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `budgetId` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `removed` | true | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).