Skip to main content

AI Credits API & Webhooks

If you embed the Unlayer builder and resell the AI Assistant to your own end-users, these endpoints give you programmatic visibility into AI credit consumption so you can build billing, set limits, and message your users.

Everything here is measured in credits — the single unit exposed across every endpoint and webhook.

Credits are pooled per workspace

A project's AI credits belong to its workspace. Every project in the same workspace draws from — and reports against — one shared balance. Webhook and alert settings, however, are configured per project.

All endpoints require an API Key (unlayer_sk_*) scoped to the project, sent as a bearer token. See Authentication. A key can only access its own project.

If you call these endpoints with a Personal Access Token instead, your account must be an admin or owner of the project — these endpoints expose the webhook signing secret and destination URL. Other roles receive 403.

An OAuth access token can read the balance, usage, settings and delivery history. Changing settings or caps, rotating the signing secret, retrying a delivery and the end-user cap endpoints return 403 for OAuth tokens; use an API key or a Personal Access Token for those.


Endpoints​

Get credit balance​

GET /v3/projects/:id/ai-credits

Returns a near-real-time snapshot of the current workspace credit pool. The project ID identifies the workspace and authorizes the request; it does not limit the balance to that project. Calling this endpoint for two projects in the same workspace returns the same balance.

{
"is_capped": true,
"credits_total": 10000,
"credits_used": 7400,
"credits_remaining": 2600,
"reset_date": "2026-08-01T00:00:00.000Z"
}

is_capped reports whether enforcement can constrain AI usage, not whether Console has a positive allowance to display. A shadow-mode workspace with a plan or add-on allowance can show a remaining allowance in Console while this endpoint returns false; the editor balance indicator stays hidden and threshold/exhausted webhooks do not fire.

When is_capped is false, usage is metered for visibility but remains uncapped: credits_total and credits_remaining describe the metered allocation, not an available balance, and reaching zero does not pause AI or create overage charges. Use credits_used to report consumption, but do not render an exhausted state from credits_remaining.

reset_date is the end timestamp returned for the current credit window, or null when the service cannot resolve an active future billing window. That includes a subscription that has been cancelled, deactivated, or reached the end of its term.

A scheduled cancellation does not make reset_date null while the current window is still active. If the subscription ends with that window, credits expire on that date rather than renewing. Annual subscriptions can still have monthly credit resets before their final term end, so do not interpret every reset_date as a subscription renewal or cancellation date.

AI credit balances update asynchronously after usage is recorded. Re-delivery of the same usage event does not consume additional credits. Current-day activity is counted by the live usage processor; reconciliation finalizes previous UTC days without adding the same activity again. A delayed or failed live update may remain absent until the next day's reconciliation.

Get usage breakdown​

GET /v3/projects/:id/ai-credits/usage

Returns the selected project's credit consumption, broken down by end user and feature type. Usage is grouped by the UTC date when the AI activity occurred. The current UTC day is updated near real time and may take a short time to appear. Each recorded AI event contributes once to this breakdown, including when its delivery is retried.

Query paramDescription
startStart date (inclusive), YYYY-MM-DD. Must be on or before end. Defaults to the active credit window's start, or 30 UTC dates before today when no active window is available.
endEnd date (inclusive), YYYY-MM-DD. Defaults to the active credit window's end, or today when no active window is available.
end_user_idFilter to a single end user.
feature_typeFilter to a single feature type.
limitMax breakdown rows to return (1–1000). Defaults to 100.
offsetNumber of breakdown rows to skip (pagination). Defaults to 0.
sortField the breakdown is ordered by: credits, end_user_id, or feature_type. Defaults to credits.
orderSort direction: asc or desc. Defaults to desc.
{
"total_credits_used": 6300,
"total": 3,
"breakdown": [
{ "end_user_id": "user_123", "feature_type": "block_edit", "credits": 200 },
{
"end_user_id": "user_456",
"feature_type": "full_template_gen",
"credits": 4000
},
{ "end_user_id": null, "feature_type": "image_generation", "credits": 2100 }
]
}
Why the totals may differ

In the examples above, the workspace has used 7400 credits, while the selected project accounts for 6300. Usage from other projects in the workspace is included in credits_used but not in total_credits_used.

The totals may also differ briefly because the workspace balance and project breakdown are updated independently from the same asynchronous event stream. Even for a single-project workspace and an unfiltered current-period query, recent usage may reach one view before the other. Settled-day finalization keeps the detailed ledger aligned with the authoritative analytics data.

When neither date is supplied and the workspace has no active credit window, the fallback covers the 30 UTC dates before today plus today itself (31 calendar dates, inclusive).

The breakdown is paginated — one end_user_id × feature_type row per entry, up to limit. It defaults to highest-credit rows first; use sort / order to change that (e.g. sort=credits&order=asc for lowest first, or sort=end_user_id alphabetically). total is the number of breakdown rows matching the filter (across all pages), for paging. total_credits_used is the credit total across the entire filtered range, not just the returned page — so you can reconcile without walking every page. Narrow the response with end_user_id / a smaller date range, or page with limit / offset.

Per-user attribution

end_user_id is populated when the AI call identifies an end user:

  • Builder — identify the user via unlayer.init({ user }). The builder forwards this user to its built-in Image Editor automatically; no additional configuration is needed.
  • Standalone Image Editor — when you initialize it yourself, pass a user to ImageEditor.createEditor().
  • Server-side AI endpoints — send end_user_id in the request body of POST /v3/templates/generate, POST /v3/templates/import, and POST /v3/images/generate.

Calls made without an identified end user are reported with end_user_id: null and still consume credits. If you already identify your users and see unexpected unattributed usage, contact support so the originating requests can be investigated.

Settlement and reconciliation​

Treat the current UTC day's breakdown as provisional. After the day closes, Unlayer replaces the streaming projection with the complete settled result. That replacement can move a total up or down because the streaming and settled pipelines are separate views and the settled snapshot replaces the day rather than adding to it.

For reliable billing and limits:

  1. Verify and deduplicate webhooks as described below, then use them for fast updates.
  2. Reconcile completed UTC days from this endpoint.
  3. Compare a workspace balance only with the sum of all projects in that workspace over the same monthly window, with no end-user or feature filter.

The workspace balance remains the authority for whether more AI work can run. The settled usage endpoint is the durable source for project, end-user, and feature attribution.

Legacy activity

Billable legacy AI actions are included in this breakdown and the usage_recorded webhook. Identify the user in the builder configuration to attribute them automatically. Historical events without a recorded user ID remain unattributed. The older per-element text suggestion endpoints exclude calls made with a supported custom provider key from their usage reporting. Current AI Assistant and image requests still consume Unlayer credits when using a custom provider key, in addition to the provider billing that account. A stored key that is not used does not change a call made with Unlayer’s key.

Update settings​

PUT /v3/projects/:id/ai-credits/settings
{
"exhaustion_behavior": "show_error",
"threshold_alerts": [80, 95],
"webhook_url": "https://partner.com/webhooks/unlayer",
"project_monthly_cap": 200000,
"end_user_monthly_cap": 2000
}
FieldDescription
exhaustion_behavior"disable" hides AI features when credits run out; "show_error" shows an error prompt.
threshold_alertsUsage percentages (1–100) at which a threshold_reached webhook fires for capped usage.
webhook_urlHTTPS endpoint that receives AI credit webhooks.
project_monthly_capMonthly AI credits the whole project may use, or null for no cap. See Monthly caps.
end_user_monthly_capDefault monthly AI credits for each end user, or null for no cap.

All fields are optional; omitted fields keep their current values.

Save your signing secret

The first time you set a webhook_url, the response includes a signing_secret — used to verify webhook signatures. It is returned once and never shown again. Store it securely.

{
"exhaustion_behavior": "show_error",
"threshold_alerts": [80, 95],
"webhook_url": "https://partner.com/webhooks/unlayer",
"has_signing_secret": true,
"signing_secret": "b1946ac9…",
"project_monthly_cap": 200000,
"end_user_monthly_cap": 2000
}

Read settings​

GET /v3/projects/:id/ai-credits/settings

Returns the project's current configuration. The signing secret itself is never returned — only whether one exists.

{
"exhaustion_behavior": "show_error",
"threshold_alerts": [80, 95],
"webhook_url": "https://partner.com/webhooks/unlayer",
"has_signing_secret": true,
"project_monthly_cap": 200000,
"end_user_monthly_cap": 2000
}
FieldDescription
exhaustion_behavior"disable" or "show_error".
threshold_alertsConfigured usage percentages that fire threshold_reached.
webhook_urlThe configured HTTPS endpoint, or null.
has_signing_secretWhether a signing secret exists (the secret is never echoed).
project_monthly_capThe project's monthly cap, or null.
end_user_monthly_capThe default monthly cap per end user, or null.

Monthly caps​

The workspace pool limits how many credits all your projects use together. Monthly caps let you set smaller limits that Unlayer enforces for you:

  • Project cap (project_monthly_cap): the most credits one project may use in a month, out of the workspace pool.
  • End-user cap (end_user_monthly_cap): the most credits each end user of the project may use in a month. Override it for one end user with the end-user endpoint.

Caps are counted in credits, from the same usage the usage breakdown reports. When a request would go over a cap, Unlayer blocks it on the server: in the builder, in the Image Editor, and through the public API. Other end users and projects keep working.

A project with no caps behaves exactly as before.

You can also manage caps in Console, under Settings → AI Credits → Monthly Caps: the project cap, the default end-user cap, and caps for specific end users. The AI Credits details panel on Console's Usage page lists each end user's credits for the current window, with the cap that applies and the credits left, and for the 11 windows before it, without caps. Export CSV downloads every end user of the window shown, in end user ID order. Both need an admin or owner role on the project.

When a cap blocks a request, Unlayer also emails the workspace owner and admins and adds a Console notification that only they see:

  • Project cap: once per project and window, within about an hour.
  • End-user caps: at most once a day per project (UTC), naming each end user blocked since the last alert with their cap (up to 10, then how many more). The day's first alert goes out within about an hour; end users blocked after it are named in the next day's. Each end user is named once per window, and only while that window is running.

Changing a cap during the window sends no new alert. Email follows the workspace's usage alert settings under Billing → Alerts.

Plans

Setting a cap to a number requires the Optimize or Enterprise plan. Other plans receive 403 FEATURE_NOT_AVAILABLE. Setting a cap to null to remove it works on every plan, and caps you already set keep applying if the plan changes.

Monthly caps are not the workspace pool

is_capped in the balance and "capped" in the webhook descriptions refer to the workspace pool. Monthly caps are separate limits you set.

When a cap blocks a request​

  • Monthly window. Caps reset with the workspace's monthly credit window, the same day its credits reset. Without an active billing period, caps use the UTC calendar month. Each UTC day counts toward one window.
  • Typical cost first. A request starts only if the remaining cap covers the feature's typical cost (from the cost estimator figures), so a large request can't start with only a few credits left. A request can still cost more than typical, so the final request of a window can go over the cap by that difference.
  • HTML files. An AI Assistant message that attaches an HTML file, or a POST /v3/templates/generate request whose last user message attaches one, starts only if the remaining cap covers an HTML import's typical cost. HTML files in earlier messages are context only, so later messages in that chat need only their own typical cost.
  • Caps smaller than one request. For the same reason, a cap below a feature's typical cost blocks that feature from the start of the window, even with no credits used. An end user can also be blocked with up to one request's typical cost still showing as remaining. An image the AI Assistant makes during a request needs both the request's typical cost and the image's left, so a cap that fits the request can still block its images. Set caps well above the typical cost of the features your end users rely on. Console warns when a cap you enter is too small for some requests and names them.
  • Simultaneous requests. While a request runs, its typical cost is held against the cap, so requests sent at the same time can't all pass the same check.
  • Usage arrives in seconds. A request's actual cost counts toward the cap a few seconds after it finishes.
  • No end user. A request without an end-user ID counts toward the project cap only.
End-user IDs must be trustworthy

An end-user cap is only as reliable as the end-user ID. Turn on identity verification so an end user can't switch IDs in the browser to get a fresh cap. The project cap still limits the total either way.

A blocked request returns 429 with the CREDITS_EXHAUSTED code, the same code used when the workspace runs out, plus a cap field naming the cap. Public API routes (POST /v3/templates/generate, POST /v3/templates/import, POST /v3/images/generate) return:

{
"error": "CREDITS_EXHAUSTED",
"code": "CREDITS_EXHAUSTED",
"message": "This user has reached their monthly AI credit cap.",
"cap": "end_user",
"reset_date": "2026-12-01T00:00:00.000Z"
}

cap is "project" or "end_user". A workspace that ran out of credits returns the same body without cap and reset_date. code repeats error under the name the builder's own AI responses use, so one check works everywhere. Pass the end user as end_user_id in the request body so their cap applies.

In the builder, AI stays available and a blocked end user sees a message that their monthly AI limit is reached and the day it resets, with no billing or upgrade action, since only you can change the cap. The editor's ai:assistant:on:error event includes cap and resetAt for these blocks. The first block in each window also sends the ai.credits.cap_reached webhook.

Get an end user's cap​

GET /v3/projects/:id/ai-credits/end-users?end_user_id=customer-42

end_user_id is the user.id you pass to the builder, exactly as the usage breakdown reports it. Send it URL-encoded; it may contain any characters.

{
"end_user_id": "customer-42",
"monthly_cap": 5000,
"monthly_cap_source": "override",
"credits_used": 1200,
"credits_remaining": 3800,
"reset_date": "2026-12-01T00:00:00.000Z"
}
FieldDescription
monthly_capThe cap that applies to this end user, or null when none does.
monthly_cap_source"override" (set for this end user), "project_default" (end_user_monthly_cap), or "none".
credits_usedCredits this end user has used in the current window.
credits_remainingCredits left under the cap, or null when there is no cap.
reset_dateWhen the window ends and usage starts over.

Set an end user's cap​

PUT /v3/projects/:id/ai-credits/end-users
{
"end_user_id": "customer-42",
"monthly_cap": 5000
}

Replaces the project's end_user_monthly_cap for this end user. Use "monthly_cap": null to give the end user no cap at all, for example for your own staff. Returns the same body as the GET.

Remove an end user's cap​

DELETE /v3/projects/:id/ai-credits/end-users?end_user_id=customer-42

Removes the cap set for this end user, so end_user_monthly_cap applies to them again. Returns the same body as the GET, showing the cap that now applies. It succeeds when no cap was set.


Webhooks​

When a webhook_url is configured, Unlayer POSTs the following events to it. The setting applies to the whole project; it cannot be limited to selected end users. Filter data.end_user_id in your receiver, or query that end user from the usage endpoint.

EventFires when…
ai.credits.usage_recordedAfter each classified real-time AI call.
ai.credits.threshold_reachedCapped usage crosses a configured percentage.
ai.credits.exhaustedA capped workspace balance reaches zero credits.
ai.credits.cap_reachedA monthly cap blocks a request for the first time in a window.

Every request body has the shape { "event": "<name>", "data": { … } }.

ai.credits.usage_recorded​

{
"event": "ai.credits.usage_recorded",
"data": {
"project_id": 123,
"end_user_id": "user_123",
"feature_type": "block_edit",
"credits_deducted": 3,
"timestamp": "2026-07-01T12:00:00.000Z"
}
}

feature_type carries the same values as the usage endpoint, listed under Feature types. Handle an unrecognized one rather than switching exhaustively: image_edit is new, and the set can grow again.

Use this event for low-latency updates, not as the final billing total. The payload for an individual call is not revised after delivery, while the settled usage endpoint aggregates a complete day. Summing webhook credits_deducted values can therefore differ from the settled API total.

ai.credits.threshold_reached​

Fires once per configured threshold per billing period for a capped workspace. Uncapped usage does not emit threshold events. If the credit allocation increases mid-period (an add-on or plan change), the threshold re-arms and fires again the next time it's crossed against the larger allocation.

{
"event": "ai.credits.threshold_reached",
"data": {
"project_id": 123,
"threshold": 80,
"credits_remaining": 2000,
"credits_total": 10000,
"timestamp": "2026-07-01T12:00:00.000Z"
}
}

ai.credits.exhausted​

Fires once per billing period when a capped workspace pool reaches 0. Uncapped usage does not emit exhausted events because reaching the metered allocation does not pause AI. If the customer tops up mid-period (an add-on or plan change) and then exhausts the larger allocation, it fires again — so a top-up that runs out is not silently missed.

{
"event": "ai.credits.exhausted",
"data": {
"project_id": 123,
"workspace_id": 45,
"timestamp": "2026-07-01T12:00:00.000Z"
}
}

ai.credits.cap_reached​

Fires the first time a monthly cap blocks a request in a window: once for the project cap, and once per end user for end-user caps. If you raise a cap and the new cap is reached in the same window, it fires again.

{
"event": "ai.credits.cap_reached",
"data": {
"project_id": 123,
"end_user_id": "customer-42",
"cap": "end_user",
"monthly_cap": 5000,
"credits_used": 4950,
"reset_date": "2026-12-01T00:00:00.000Z",
"timestamp": "2026-11-20T12:00:00.000Z"
}
}

cap is "project" or "end_user". end_user_id is null for the project cap. credits_used includes requests that were still running.

Delivery timing

usage_recorded and cap_reached are delivered in real time. threshold_reached and exhausted are derived from aggregated usage and may lag actual consumption by up to an hour.

Verifying signatures​

Each delivery carries four headers:

HeaderValue
X-Unlayer-Signaturesha256=<hex> HMAC of the request.
X-Unlayer-TimestampUnix milliseconds when the request was signed.
X-Unlayer-EventThe event name.
X-Unlayer-Delivery-IdStable id for tracing a delivery across attempts.

Handling duplicates​

Delivery is at-least-once: a failed delivery is retried automatically, and a delivery can occasionally be sent more than once even after it has succeeded — for example if a retry was already in flight when the first attempt landed.

Verify the signature and timestamp freshness before processing or deduplicating a request. Then use X-Unlayer-Delivery-Id to collapse ordinary at-least-once retries; it stays the same across attempts of one delivery:

const deliveryId = headers['x-unlayer-delivery-id'];

if (typeof deliveryId !== 'string' || !deliveryId) {
return res.sendStatus(400);
}

if (await alreadyProcessed(deliveryId)) {
return res.sendStatus(200); // already handled — acknowledge and stop
}

The signature authenticates the timestamp and raw body, but not X-Unlayer-Event or X-Unlayer-Delivery-Id. Use the event name from the verified body. The delivery id handles normal retry duplication; it is not replay-proof because it is unsigned. Keep the timestamp tolerance narrow, make downstream writes idempotent where your data model allows it, and use the settled usage endpoint—not webhook deduplication alone—as the billing authority.

Always respond 2xx to a duplicate. A non-2xx response marks the delivery failed and schedules another retry.

The signature is an HMAC-SHA256 over the string `${timestamp}.${rawBody}` using your signing_secret. Compute it yourself and compare in constant time:

import crypto from 'node:crypto';

function isValid(rawBody, headers, secret) {
const timestamp = headers['x-unlayer-timestamp'];
const received = headers['x-unlayer-signature'];
const signedAt = Number(timestamp);

if (
typeof timestamp !== 'string' ||
typeof received !== 'string' ||
!Number.isSafeInteger(signedAt) ||
Math.abs(Date.now() - signedAt) > 5 * 60 * 1000
) {
return false;
}

const expected =
'sha256=' +
crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');

return (
expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
);
}

Sign over the raw request body, before any JSON parsing — re-serializing can change bytes and break the comparison. The five-minute tolerance above is an example; choose a short window that fits your delivery latency and clock-skew requirements.

Delivery & retries​

Return a 2xx to acknowledge a webhook. A non-2xx response (or a timeout — endpoints have ~10s to respond) is retried. Each delivery is attempted up to 3 times in quick succession (~90s apart); if it still hasn't succeeded, it is re-attempted periodically for a while afterward, so a transient outage on your endpoint recovers on its own. Because a delivery can be retried, your endpoint must be idempotent — the same event may arrive more than once, and events are not guaranteed to arrive in order.

Delivery history & manual retry​

All events — usage_recorded, threshold_reached, and exhausted — are tracked in the delivery history. Inspect recent deliveries and re-send failed ones without waiting for the automatic retry.

List deliveries​

GET /v3/projects/:id/ai-credits/webhooks/deliveries

The delivery history, newest first.

Query paramDescription
statusFilter to a single status: pending / delivered / failed.
eventFilter to a single event.
limitMax deliveries to return (1–100). Defaults to 50.
offsetNumber of deliveries to skip (pagination). Defaults to 0.

Each delivery has event, status, attempts, last_status_code, end_user_id (when the event carries one), created_at, and delivered_at. The response also includes total — all deliveries matching the filter, ignoring paging.

List a delivery's attempts​

GET /v3/projects/:id/ai-credits/webhooks/deliveries/:deliveryId/attempts

The per-attempt history for one delivery, newest attempt first. Returns 404 if the delivery isn't found for this project.

Query paramDescription
limitMax attempts to return (1–100). Defaults to 50.
offsetNumber of attempts to skip (pagination). Defaults to 0.

Each attempt has attempt (the attempt number), status_code, error, and attempted_at, plus a total.

Retry a delivery​

POST /v3/projects/:id/ai-credits/webhooks/deliveries/:deliveryId/retry

Re-queue one delivery for another attempt. Returns 409 if it was already delivered. Retries deliver to your current webhook URL and signing secret, so correcting a wrong URL and retrying recovers the events that failed against the old one.

Retention

usage_recorded is high volume (one per AI call), so its rows are pruned from the history: successfully-delivered rows after 30 days, and failed or pending rows after 90 days (long past the last automatic retry) — filter with ?event=ai.credits.usage_recorded to find recent ones. threshold_reached and exhausted deliveries are retained. For a complete billing record, the usage breakdown endpoint remains the durable source of truth.

Rotating the signing secret​

POST /v3/projects/:id/ai-credits/settings/rotate-secret returns a new signing secret once. The previous secret stops working immediately, so update your verification before rotating. To check whether a secret is set without rotating, use Read settings.

A webhook_url is required — the signing secret is generated when you first set one. Rotating before then returns 400.


Feature types​

feature_type classifies what an AI call did:

feature_typeMeaning
full_template_genGenerating a full template / layout.
block_editEditing a block, generating text suggestions, or automatically describing an image.
html_importImporting a design from HTML.
image_importReconstructing an editable design from an image or screenshot.
image_generationGenerating a new image from a prompt.
image_editEditing an image that already exists.

The last two are distinguished by the operation. The builder AI Assistant and Images API can generate new images or edit existing ones; the standalone Image Editor edits its current image.

One Assistant turn can produce a text/design usage event plus one image_generation or image_edit event per image operation. The chat and conversational API total include those image operations; they are not charged again as text. Automatic alt text is a separate block_edit call after an image is added or changed through AI. Ordinary uploads, URL changes, and edits made without AI do not trigger this call. Uploading, reordering, previewing, adding a result to the prompt, and using Undo change do not themselves run a paid image operation.

Legacy Smart Headings, Smart Text, Smart Buttons, and image-to-text suggestions are included as block_edit. Legacy Magic Image generation and its image-prompt suggestions are included as image_generation. These actions already consumed credits; including them in the usage breakdown and usage webhooks does not add another charge. The builder's existing user identification supplies their end-user attribution automatically. Direct project-key calls to legacy text routes have no end-user identity and are reported as unattributed.

Older legacy events that are reprocessed can appear in these categories, but events recorded without an end-user ID remain unattributed. This change does not reconstruct missing identities or automatically backfill all past usage.

image_edit is new

AI image edits used to be reported as image_generation. They now have their own feature_type, so a filter or chart pinned to image_generation no longer includes them. If you break usage down by feature, add image_edit to whatever you already do for image_generation. Usage recorded before this change keeps its original image_generation classification; nothing is reclassified retroactively.