Daily spend limit

A limit in rupees for one India day. Once today's spend reaches it, new broadcasts are refused until midnight. The account owner reads and sets it from a signed-in panel session.

GET /api/v1/rcs/spend-limit
PUT /api/v1/rcs/spend-limit

A day runs midnight to midnight, India time (IST). Today's spend is what was charged today, on prepaid and postpaid accounts alike: the same figure as the spend on your dashboard. Money held for a broadcast that has not sent yet is not spend.

Who can call it

Only the account owner, from a signed-in panel session. Operators and viewers get 403 not_owner. An API key gets 403 api_key_endpoint_not_allowed at any scope, so a leaked key cannot lift the guard on your spending.

Read the limit

GET

/api/v1/rcs/spend-limit

JWTowner

{
  "success":     true,
  "daily_limit": 5000,
  "today_spend": 4120.5,
  "spend_known": true,
  "percent":     82.41,
  "state":       "near",
  "day":         "2026-09-27",
  "resets_at":   "2026-09-27T18:30:00Z"
}

Field	Type	Meaning
`daily_limit`	number or null	The limit in rupees. `null` when no limit is set.
`today_spend`	number or null	What was charged today, in rupees, to the paisa. Filled even with no limit set. `null` when it could not be read.
`spend_known`	bool	`false` when today's spend could not be read.
`percent`	number or null	`today_spend` as a share of `daily_limit`, to 2 decimals. `null` with no limit, or when the spend is not known.
`state`	string	Where today stands, see below.
`day`	string	Today's date in India, `YYYY-MM-DD`.
`resets_at`	string	The next midnight in India, in UTC.

`state`	Meaning
`none`	No limit is set.
`ok`	Under 80% of the limit.
`near`	80% or more. The owner gets a panel notice and, once that day, an email.
`reached`	100% or more. New broadcasts are refused, see What the limit refuses.
`unknown`	A limit is set, but today's spend could not be read. Nothing is refused while it is unknown.

With no limit set:

{
  "success":     true,
  "daily_limit": null,
  "today_spend": 4120.5,
  "spend_known": true,
  "percent":     null,
  "state":       "none",
  "day":         "2026-09-27",
  "resets_at":   "2026-09-27T18:30:00Z"
}

Status	`code`	When
`500`	`spend_limit_unavailable`	`Could not load the spend limit. Try again.` The limit itself could not be read. A spend that cannot be read is not an error: it comes back with `spend_known: false`.

Set or turn off the limit

PUT

/api/v1/rcs/spend-limit

JWTowner

PUT /api/v1/rcs/spend-limit
{ "daily_limit": 5000 }

A number from 1 to 10000000 (₹1 to ₹1,00,00,000) sets the limit. It is rounded to 2 decimals.
null or 0 turns the limit off.

The change counts at once, and the answer is the same body as the GET. After a change, the owner is told again if the new limit is crossed that day; the email still comes at most once a day. Every change is recorded in the audit log as settings.spend_limit_updated, with the new and the previous limit.

Status	`code`	When
`400`	`invalid_limit`	`Enter a daily limit between ₹1 and ₹1,00,00,000, or turn the limit off.` The field is missing, not a number, or outside 1 to 10000000.
`500`	`save_failed`	`Could not save the limit. Try again.` Nothing changed.

What the limit refuses

Once state is reached, these calls answer HTTP 409 before the broadcast itself is checked. Nothing is saved, started or held.

Call	Refused
`POST /broadcasts`	When the broadcast would send today: no `scheduled_at` (or `scheduled_send_at`), or one before the next India midnight. One scheduled for a later day is accepted.
`POST /broadcasts/{id}/start`	When the broadcast has no `scheduled_at`, or one before the next India midnight.
`POST /broadcasts/{id}/send-now`	Always.

{
  "success":     false,
  "error":       "spend_limit_reached",
  "code":        "spend_limit_reached",
  "message":     "Today's spend limit of ₹5,000 is reached. New broadcasts can start again after midnight, or the account owner can raise the limit in Settings.",
  "daily_limit": 5000,
  "today_spend": 5012.4,
  "resets_at":   "2026-09-27T18:30:00Z"
}

Branch on code. Wait until resets_at, or ask the owner to raise the limit.

While the limit is reached, the send side also acts on its own:

A scheduled broadcast that has never sent and falls due does not start. It ends failed with status_reason: "spend_limit_reached" on Get. Nothing is sent, and a prepaid hold is released. Send it again with a new Create.
A recurring run that falls due is skipped: no child broadcast, and the schedule carries on at its next time.

Not refused and not stopped:

A broadcast that is already running, including one paused overnight by the promotional time window. A day's spend can pass the limit.
Single messages from send message, and test sends.
Retarget, which only builds a list.
Creating, updating, pausing or resuming a recurring broadcast.

It fails open

The limit guards your budget. If the limit or today's spend cannot be read at that moment, the call goes through rather than refusing a send. A charge that is reported very late can also be left out of that day's total, so a day can pass the limit by that amount.

Live event

When today's spend passes 80% or 100% of the limit, the panel's live event stream carries a spend.alert event:

{
  "type": "spend.alert",
  "data": {
    "state":       "near",
    "daily_limit": 5000,
    "today_spend": 4120.5,
    "percent":     82.41,
    "day":         "2026-09-27"
  }
}

state is near or reached. Each crossing is sent once a day, and again after the limit is changed. Today's spend is checked every few minutes, so the event can come a few minutes after the line is crossed.

Broadcasts

The refusal on Create, Start and Send now.

Settings

Setting the limit in the panel.

Daily spend limit

Read the limit#

Set or turn off the limit#

What the limit refuses#

Live event#

Read the limit

Set or turn off the limit

What the limit refuses

Live event