AI Credits

AI Credits

Five webhook events let you track your agency's AI credit pool and client wallet events without polling.

• Account credit pool: The AI credit balance of your agency from your plan allowance and purchased top-ups.
• Client wallet: A spending limit that your agency sets on a client account.

Common use cases include:

• Warn a client before their wallet runs out of credits.
• Alert your team or purchase top-ups before your account pool is empty.
• Keep your external records of client wallet balances synchronized.

Subscribing to AI Credits Events

To receive these events, create an account-scoped webhook subscription using the Create Webhook endpoint:

POST /api/sites/multiscreen/webhooks
{
  "resource_type": "ACCOUNT",
  "event_types": [
    "AI_CREDITS_ACCOUNT_THRESHOLD_REACHED",
    "AI_CREDITS_WALLET_THRESHOLD_REACHED",
    "AI_CREDITS_WALLET_CREDITS_ADDED",
    "AI_CREDITS_WALLET_CREDITS_RESET",
    "AI_CREDITS_WALLET_DELETED"
  ],
  "endpoint": "https://example.com/duda-webhooks"
}

• Account scope: Set resource_type to ACCOUNT. Do not provide resource_id. Duda identifies the account from your API credentials.
• Site scope: Webhook subscriptions with resource_type: "SITE" never receive these events.
• List event types: You can retrieve all supported event types with GET /api/sites/multiscreen/webhooks/event-types.

Usage Thresholds and Measurement

Usage thresholds trigger at fixed levels: 80%, 95%, and 100% used. You cannot configure custom threshold values.

• 80: 20% or less of the allowance remains.
• 95: 5% or less of the allowance remains.
• 100: No credits remain (0% remaining).

How usage is calculated:

• Account credit pool: Remaining monthly credits plus top-up credits, measured against the monthly plan allowance. Daily credits are not counted.
• Client wallet: The sum of recurrence_balance and topup_balance, measured against recurrence_amount.

Events Not Covered

• Partner API changes: Webhook events do not trigger when you create a wallet, update a wallet, assign or unassign a client, or remove credits. Your Partner API requests already return the updated wallet object.
• Client notifications: Duda sends automatic email notifications to the account owner for the account credit pool only. Duda does not send emails for client wallets. Use these webhooks to send custom notifications to your clients.

Webhook Delivery Payload

All five events use the same envelope structure:

• data: Contains the event-specific data.
• source: Always null.
• resource_data: Always {} (empty object).
• event_timestamp: Epoch timestamp in milliseconds.
• event_type: The event name.

Additional field conventions:

• wallet_id and wallet_name: The ID and name of the wallet in the Client Wallets API. If no name was configured, wallet_name equals wallet_id.
• Balances (recurrence_balance, topup_balance): Decimal strings with two decimal places (such as "0.00"), measured in AI credits. They reflect balance values after the change.
• credit_type: The balance that received credits (RECURRENCE or TOPUP).
• amount: The amount of credits added, as a decimal string.

Account Threshold Reached

Duda sends a notification when AI usage causes the agency's credit pool to reach 80% used, 95% used, or empty. Event type: AI_CREDITS_ACCOUNT_THRESHOLD_REACHED

{
  "data": {
    "threshold": 80
  },
  "source": null,
  "resource_data": {},
  "event_timestamp": 1791457918357,
  "event_type": "AI_CREDITS_ACCOUNT_THRESHOLD_REACHED"
}

Wallet Threshold Reached

Duda sends a notification when a client's AI usage causes their wallet to reach 80% used, 95% used, or empty. Event type: AI_CREDITS_WALLET_THRESHOLD_REACHED

{
  "data": {
    "threshold": 100,
    "wallet_id": "fa41a54a-9e38-4b0d-bf27-4e384283e85c",
    "wallet_name": "wh-W4",
    "recurrence_balance": "0.00",
    "topup_balance": "0.00"
  },
  "source": null,
  "resource_data": {},
  "event_timestamp": 1791457918357,
  "event_type": "AI_CREDITS_WALLET_THRESHOLD_REACHED"
}

Wallet Credits Added

Duda sends a notification when credits are added to a wallet through POST /api/ai-credits/wallets/{wallet_id}/credits with a positive amount. Event type: AI_CREDITS_WALLET_CREDITS_ADDED

{
  "data": {
    "wallet_id": "fa41a54a-9e38-4b0d-bf27-4e384283e85c",
    "wallet_name": "wh-W4",
    "credit_type": "TOPUP",
    "amount": "50.00",
    "recurrence_balance": "20.00",
    "topup_balance": "50.00"
  },
  "source": null,
  "resource_data": {},
  "event_timestamp": 1791457918357,
  "event_type": "AI_CREDITS_WALLET_CREDITS_ADDED"
}

Wallet Credits Reset

Duda sends a notification when a wallet's monthly allowance refills on its recurrence_day, even when the wallet was already full. Event type: AI_CREDITS_WALLET_CREDITS_RESET

{
  "data": {
    "wallet_id": "fa41a54a-9e38-4b0d-bf27-4e384283e85c",
    "wallet_name": "wh-W4",
    "recurrence_balance": "100.00",
    "topup_balance": "25.00"
  },
  "source": null,
  "resource_data": {},
  "event_timestamp": 1791457918357,
  "event_type": "AI_CREDITS_WALLET_CREDITS_RESET"
}

Wallet Deleted

Duda sends a notification when a wallet is deleted through DELETE /api/ai-credits/wallets/{wallet_id}. Event type: AI_CREDITS_WALLET_DELETED

{
  "data": {
    "wallet_id": "fa41a54a-9e38-4b0d-bf27-4e384283e85c",
    "wallet_name": "wh-W4"
  },
  "source": null,
  "resource_data": {},
  "event_timestamp": 1791457918357,
  "event_type": "AI_CREDITS_WALLET_DELETED"
}