Skip to main content

Volume Limit Webhook Events

Overview

Each merchant account (credential profile, or MID) can carry a monthly volume limit per UTC calendar month:

  • Hard limit: Gateway atomically reserves headroom before dispatching new sales, authorizations (including wallet), and recurring payments. Requests that exceed the MID's remaining monthly headroom are declined (volume_limit_exceeded). Captures, voids, refunds, incremental auths, and force-posts of already-approved voice authorizations are not checked. Terminal-approved payments count on sync, may put usage over the limit, and cannot be declined retroactively. Bolt's precheck does not reserve headroom; concurrent Bolt-approved terminal payments may also exceed the limit. The limit resets on the 1st (UTC).
  • Soft limit: an optional early-warning level below the hard limit. When approved volume first reaches or exceeds it, the gateway triggers one notification for the MID's owning agent per UTC month. This is an alert only; payments are not declined at the soft limit.

Events are delivered through the standard webhook pipeline (signed HMAC body with delivery retries) to event subscriptions. All amounts are integer minor units of currency. All timestamps are ISO-8601 UTC instants.

Event types

risk.volume_limit.soft_limit_reached

Fires at most once per MID per UTC calendar month: on the first approval that brings the month's approved volume to or above the soft limit. Later approvals in the same UTC month, retries, and additional gateway replicas do not fire it again. The next UTC month starts fresh.

The event is organization-scoped (no merchantId). It is delivered to:

  • ORGANIZATION-scope subscriptions for the organization, and
  • AGENT-scope subscriptions of the agent hierarchy that owns the organization (the owning agent and its ancestors). Other agents never receive it.

agentId is the organization's owning agent, or null for an organization without one. approvedMinor is the approved volume when the soft limit was reached; periodEnd is exclusive.

{
  "organizationId": "org_abc",
  "credentialProfileId": "7c0d4c1e-7a3b-4f55-9e57-2f5a1f0c9d11",
  "credentialProfileName": "Main Street MID",
  "agentId": "agt_summit",
  "periodStart": "2026-10-01T00:00:00Z",
  "periodEnd": "2026-11-01T00:00:00Z",
  "currency": "USD",
  "softLimitMinor": 4000000,
  "hardLimitMinor": 5000000,
  "approvedMinor": 4012345,
  "crossedAt": "2026-10-14T15:02:11.482Z"
}

The owning agent's email goes to the agent's contact email on file. Its outcome (sent, failed and retried, no agent, or no agent email) is shown with the merchant account's volume limit in the Risk & Reserves pages.

See Event log and replay.