Admin Guide
Billing Controls
The daily job that charges everyone, and the logs that show what it did.
Last updated 2026-10-13
DigitalKey ERP — Docs · digital-key.co/docs/admin/billing
The daily billing run
Each run does two things, in order:
- Deducts from every user whose
next_billing_athas arrived. - Advances anyone sitting in
temp_suspendorsuspendwhose grace period has expired, and disables expired demo tenancies.
POST /api/v1/admin/billing/run-daily
| Parameter | Type | Required | Description |
|---|---|---|---|
x-cron-secret | header | Optional | Shared secret. Accepted instead of an admin token so a scheduler can drive it. |
Triggering the run
curl -X POST https://api.digital-key.co/api/v1/admin/billing/run-daily \
-H "x-cron-secret: <CRON_SECRET>" \
-H "Content-Type: application/json" \
-d '{}'What the run returns
| Parameter | Type | Required | Description |
|---|---|---|---|
users_processed | integer | Optional | How many users were due and considered. |
users_succeeded | integer | Optional | How many were charged successfully. |
users_failed | integer | Optional | How many failed for want of balance. |
users_suspended | integer | Optional | How many moved to a more restricted state. |
total_deducted | decimal | Optional | Total collected in this run, in IQD. |
run_at | timestamp | Optional | When the run happened. |
errors[] | array | Optional | Anything that went wrong during the run. |
TipThe run is safe to trigger more than once. Deductions are idempotent per period, so a user already settled for the month is skipped rather than charged again — a missed or repeated run does no damage.
WarningNothing inside the application schedules this. It must be driven from outside — a host cron job,
pg_cron, or an external scheduler. If it is never called, nobody is billed and nobody is ever suspended.Billing status
GET /api/v1/admin/billing/status
| Parameter | Type | Required | Description |
|---|---|---|---|
users_due_today | integer | Optional | How many users are due to be billed today. |
suspended_users | integer | Optional | How many are currently in a suspended state. |
last_billing_run_at | timestamp | Optional | When the job last ran. |
total_deducted_this_month | decimal | Optional | Collected so far this month. |
Important
last_billing_run_at is the number to watch. If it is more than a day old, the scheduler has stopped and revenue is not being collected — check it before investigating individual customer complaints.Admin — Billing screen

The deduction log
GET /api/v1/admin/billing-log
| Parameter | Type | Required | Description |
|---|---|---|---|
deduction_id | integer | Optional | Identifier. |
username | string | Optional | Who was charged. |
full_name | string | Optional | Their display name. |
tenant_name | string | Optional | Their business. |
feature_name | string | Optional | Which feature the row is for. |
module_name | string | Optional | Which module that feature belongs to. |
amount | decimal | Optional | Amount deducted, in IQD. |
period_month | date | Optional | The month being paid for. |
status | string | Optional | success, failed_low_balance or free. |
deducted_at | timestamp | Optional | When it ran. |
GET /api/v1/admin/billing-stats
| Parameter | Type | Required | Description |
|---|---|---|---|
this_month | decimal | Optional | Collected this month. |
last_month | decimal | Optional | Collected last month. |
success_count | integer | Optional | Successful deductions. |
failed_count | integer | Optional | Failed deductions. |
NoteThere is one row per feature, per user, per month — not one per user. A user with four paid features produces four rows each month.
The top-up log
GET /api/v1/admin/topups
| Parameter | Type | Required | Description |
|---|---|---|---|
topup_id | integer | Optional | Identifier. |
username | string | Optional | Who was credited. |
tenant_name | string | Optional | Their business. |
amount | decimal | Optional | Amount credited, in IQD. |
topped_up_by_role | string | Optional | Whether an admin or a reseller did it. |
topped_by_name | string | Optional | Who performed it. |
payment_method | string | Optional | How the customer paid, when recorded. |
notes | string | Optional | Reference or reason. |
created_at | timestamp | Optional | When it was credited. |
GET /api/v1/admin/topups-stats
| Parameter | Type | Required | Description |
|---|---|---|---|
total_all | decimal | Optional | All top-ups ever. |
this_month | decimal | Optional | Top-ups this month. |
topup_count | integer | Optional | Number of top-ups. |
TipThe top-up log is the audit trail for money coming in. When a customer disputes a payment, this is the record that settles it — it shows who credited what, when, and with what reference.
Related
- How Billing Works — the model behind the run.
- Lifecycle States — what the run does to suspended users.
- Platform Settings — tuning the grace periods.