License Enforcement Guide

FiscalAPI Embedded-Local deployments enforce merchant limits tied to your license. When you exceed your licensed merchant count, a grace period begins before enforcement activates.

How it works

Your Embedded-Local agent sends periodic heartbeats to the management plane. Each heartbeat includes the current merchant count across all locations under your license. The management plane compares this against your license's max_merchants limit.

Agent heartbeat → Management plane checks merchant count
                → Under limit: no action
                → Over limit: grace period begins

Unlimited licenses

If your license has max_merchants set to 0 (or null), merchant limits are not enforced. This applies to enterprise agreements with unlimited merchant provisioning.

Grace period

When your merchant count exceeds the license limit, a 14-day grace period begins:

Day	Action
1	Grace period starts. Notification email sent.
2 -- 6	No action. Existing merchants continue to work.
7	Second notification email sent.
8 -- 12	No action.
13	Final warning email sent.
14+	Enforcement active. New merchant onboarding blocked.

During the grace period:

• All existing merchants continue to operate normally
• You can still process transactions for all merchants
• New merchant onboarding is not blocked until day 14

Enforcement

Once enforcement activates (day 14+), new merchant creation is blocked. The heartbeat response includes enforcement status:

{
  "enforcement_active": true,
  "merchants_used": 55,
  "merchants_max": 50,
  "grace_period_active": false,
  "grace_period_end": "2026-03-01T00:00:00Z"
}

Existing merchants and their transactions are never affected by enforcement. Only new merchant onboarding is blocked.

Resolving violations

To resolve a merchant limit violation:

1. Reduce merchants -- Remove unused merchant locations to bring the count under your limit
2. Upgrade your license -- Contact sales to increase your max_merchants allowance

When the merchant count drops to or below the limit, the violation is automatically resolved and enforcement is lifted. No restart or manual intervention is required.

Checking enforcement status

The agent's heartbeat response includes current enforcement state. You can monitor this in your Embedded-Local agent's logs or dashboard.

Field	Type	Description
enforcement_active	boolean	Whether new merchant onboarding is blocked
merchants_used	integer	Current merchant count across all locations
merchants_max	integer	Licensed maximum (null = unlimited)
grace_period_active	boolean	Whether the 14-day grace period is in progress
grace_period_end	datetime	When enforcement will activate (if grace period active)