Configure alert thresholds for transaction limits

To receive notifications when a card's remaining spending limit falls below a specified level, configure alert settings on each card using the alert_settings object and subscribe to the corresponding webhook event. This lets you proactively top up, adjust limits, or notify cardholders before transactions are declined.

Before you begin

• Your Airwallex account has Issuing enabled and you can create and manage cards with transaction limits.
• You have an HTTPS endpoint available to receive webhooks and can configure it in the Airwallex web app or via API.
• You have obtained an access token API for API calls.

Configure alert settings on the card

Alert settings are configured per card. You set them when creating a card or when updating an existing card. The alert_settings object contains alert configuration for the card. Within low_remaining_transaction_limit, set enabled (required, boolean) to turn the alert on or off and percent (required, integer) to the percentage threshold. When the remaining spending limit falls at or below that percentage, a webhook is triggered.

• Only one notification per spend limit interval is sent. The webhook fires when the threshold is crossed; further spending below the threshold does not trigger additional notifications for that interval.
• If the spend limit is updated, a new notification is sent when the new threshold is crossed.
• This alert applies only to multiple-use cards.
• If low_remaining_transaction_limit is not specified, it is enabled by default with enabled set to true and percent set to an account-specific default.

1. In your Create a card API or Update a card API request, include the alert_settings object with low_remaining_transaction_limit and the enabled and percent fields. For the full structure, refer to the Create a card API and Update a card API API reference.

2. Submit the request. Once the card has alert settings configured, Airwallex will send the issuing.card.low_remaining_transaction_limit webhook event when the card's remaining spending limit falls below the specified threshold.

Example request (Update a card with alert settings)

1curl -X POST https://api-demo.airwallex.com/api/v1/issuing/cards/{{CARD_ID}}/update \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "alert_settings": {
6      "low_remaining_transaction_limit": {
7        "enabled": true,
8        "percent": 10
9      }
10    }
11  }'

Example response

1{
2  "card_id": "c5caf0ab-287c-4f74-8cde-84d52352bda3",
3  "alert_settings": {
4    "low_remaining_transaction_limit": {
5      "enabled": true,
6      "percent": 10
7    }
8  }
9}

Subscribe to the low-remaining-limit webhook

To receive alerts when a card's remaining limit falls below your threshold, your system must receive the Issuing webhook event.

1. Configure a webhook endpoint in the Airwallex web app under the Developer area, or via the webhooks API. Use an HTTPS URL that your server can receive POST requests on.

2. Subscribe to the issuing.card.low_remaining_transaction_limit event type for the webhook endpoint. This event is sent when the card's remaining spending limit has fallen below the specified threshold.

3. Ensure your endpoint correctly verifies the webhook signature and returns a 2xx response so that Airwallex does not retry unnecessarily.

For full webhook setup steps, see Listen for webhook events and Issuing webhook events.

Handle the webhook event

When a card's remaining limit drops at or below your threshold, Airwallex sends an issuing.card.low_remaining_transaction_limit event to your endpoint.

Webhook payload example (issuing.card.low_remaining_transaction_limit)

1{
2  "id": "2a396f97-92f4-3075-98fa-43acf6e87412",
3  "name": "issuing.card.low_remaining_transaction_limit",
4  "account_id": "acct_t6nlGSCgPpWIBE-3ncOTxA",
5  "data": {
6    "currency": "USD",
7    "limits": [
8      {
9        "amount": 1000,
10        "interval": "DAILY",
11        "remaining": 149
12      }
13    ]
14  },
15  "created_at": "2026-03-03T09:12:34+0000",
16  "version": "2025-08-29"
17}

1. Parse the webhook payload. The event data contains currency and a limits array; each limit object has amount, interval, and remaining so you can see which limit(s) have fallen below the alert threshold.

2. Use the event to trigger your chosen action. Common options include:

   • Calling Get card remaining limits API to get the current remaining amounts per interval.
   • Adjust limits via Update a card API if your use case allows it.
   • Notifying the cardholder or your support team so they can request an increase.

3. Log or store the event for auditing and operational visibility.

Next steps

After configuring alert thresholds and handling the webhook, you can:

• Review Alert thresholds for transaction limits for more context on how thresholds relate to transaction limits.
• Use Get card remaining limits API to check remaining spend when you receive an alert or as part of your workflows.
• Manage transaction limits on cards when you create or update them.