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:

  1. Deducts from every user whose next_billing_at has arrived.
  2. Advances anyone sitting in temp_suspend or suspend whose grace period has expired, and disables expired demo tenancies.
POST /api/v1/admin/billing/run-daily
ParameterTypeRequiredDescription
x-cron-secretheaderOptionalShared 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
ParameterTypeRequiredDescription
users_processedintegerOptionalHow many users were due and considered.
users_succeededintegerOptionalHow many were charged successfully.
users_failedintegerOptionalHow many failed for want of balance.
users_suspendedintegerOptionalHow many moved to a more restricted state.
total_deducteddecimalOptionalTotal collected in this run, in IQD.
run_attimestampOptionalWhen the run happened.
errors[]arrayOptionalAnything 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
ParameterTypeRequiredDescription
users_due_todayintegerOptionalHow many users are due to be billed today.
suspended_usersintegerOptionalHow many are currently in a suspended state.
last_billing_run_attimestampOptionalWhen the job last ran.
total_deducted_this_monthdecimalOptionalCollected so far this month.
Importantlast_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
Billing screen
Billing screen — Billing statistics with the deduction log and its filters.

The deduction log

GET /api/v1/admin/billing-log
ParameterTypeRequiredDescription
deduction_idintegerOptionalIdentifier.
usernamestringOptionalWho was charged.
full_namestringOptionalTheir display name.
tenant_namestringOptionalTheir business.
feature_namestringOptionalWhich feature the row is for.
module_namestringOptionalWhich module that feature belongs to.
amountdecimalOptionalAmount deducted, in IQD.
period_monthdateOptionalThe month being paid for.
statusstringOptionalsuccess, failed_low_balance or free.
deducted_attimestampOptionalWhen it ran.
GET /api/v1/admin/billing-stats
ParameterTypeRequiredDescription
this_monthdecimalOptionalCollected this month.
last_monthdecimalOptionalCollected last month.
success_countintegerOptionalSuccessful deductions.
failed_countintegerOptionalFailed 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
ParameterTypeRequiredDescription
topup_idintegerOptionalIdentifier.
usernamestringOptionalWho was credited.
tenant_namestringOptionalTheir business.
amountdecimalOptionalAmount credited, in IQD.
topped_up_by_rolestringOptionalWhether an admin or a reseller did it.
topped_by_namestringOptionalWho performed it.
payment_methodstringOptionalHow the customer paid, when recorded.
notesstringOptionalReference or reason.
created_attimestampOptionalWhen it was credited.
GET /api/v1/admin/topups-stats
ParameterTypeRequiredDescription
total_alldecimalOptionalAll top-ups ever.
this_monthdecimalOptionalTop-ups this month.
topup_countintegerOptionalNumber 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