Billing Guide

How Billing Works

Balance, billing day, monthly deduction — the three ideas the whole billing system rests on.

Last updated 2026-10-13

DigitalKey ERP — Docs · digital-key.co/docs/billing

The model in three sentences

  1. Every user has their own balance in IQD — always Iraqi Dinar, whatever main currency the business itself works in.
  2. Every user subscribes to features, each with a monthly price.
  3. Once a month, on their own billing day, the total is deducted from that balance.
Billing — My Account billing panel
My Account billing panel
My Account billing panel — Balance, monthly cost, next billing date and the subscribed features that make up the total.
WarningBilling is per user, not per business. A shop with three staff has three balances and three separate monthly deductions. Topping up the owner does nothing for the cashier.

The billing day

Your billing day is the day of the month you first signed in, stored once as billing_day and never changed. First sign-in on the 15th means billing on the 15th, every month.

NoteThere is no platform-wide billing date. Users are billed on their own anniversary, so deductions are spread across the month rather than landing together.

What a deduction does

Each run, for each user due, the system:

  1. Adds up the monthly price of every active paid feature they subscribe to.
  2. Compares that total against their balance.
  3. If the balance covers it — deducts, logs each feature as success, and moves the billing dates forward.
  4. If it does not — logs failed_low_balance, moves an active user to temp_suspend, and still moves the dates forward.
ImportantA failed deduction is not retried on its own, and the billing dates advance either way — what starts is the grace-period clock. The missed month is still owed: the next top-up collects it in full before the account is reactivated. See Lifecycle States.

Adding a feature mid-month

A newly added paid feature is charged for its first month at the moment it is added, and joins the monthly deduction from then on. Each feature is tracked separately, so adding one shortly before your billing day never causes another feature's month to be skipped or charged twice.

Free-only users are still billed

NoteA user subscribed only to pos.quick_sale has a monthly total of zero. They still go through the billing run — the deduction is simply zero, is logged as free, and the dates advance as normal. They never enter a grace period because there is nothing to fail.

Deduction records

One row per feature, per month
ParameterTypeRequiredDescription
feature_keystringOptionalWhich feature was charged for.
amountdecimalOptionalAmount deducted for it, in IQD.
period_monthdateOptionalThe month being paid for.
statusstringOptionalsuccess, failed_low_balance or free.
deducted_attimestampOptionalWhen the run happened.
TipDeductions are idempotent per feature and period. If a billing run is triggered twice for the same month — or the nightly run and a login land together — the second pass sees the period is already settled and does nothing. You cannot be double-charged by a re-run.

Top-ups

Balance is added by a platform administrator or by your reseller. Users cannot top themselves up.

POST /api/v1/admin/billing/topup
ParameterTypeRequiredDescription
user_idintegerRequiredWho is being credited.
amountdecimalRequiredAmount to add, in IQD.
notesstringOptionalReason or reference for the top-up.
WarningTop-ups are guarded against duplicates: the same user and the same amount within five seconds is treated as one action. This stops a double-click creating two credits, but it also means two genuine identical top-ups seconds apart will only register once — wait a moment between them.
TipA top-up to a suspended account first collects the month that failed, then reactivates the account — there is no separate reactivation step. A top-up too small to cover what is owed is kept on the balance and the account stays suspended.

When billing runs

Deductions are triggered from two places:

  • First login — activates the account and takes the first month.
  • The daily run — processes everyone whose next_billing_at has arrived, then advances anyone sitting in a suspended state past their grace period.
Triggering the daily 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 '{}'
NoteThe endpoint accepts either an admin token or the shared cron secret, so it can be driven by a scheduler without an interactive login. See Billing Controls.

Billing never blocks work

NoteBilling triggered at login runs in the background and is wrapped so that a failure cannot stop you signing in. If billing is broken, you are still let in — you simply will not have been charged.

In this section