> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upcoming Charge Funding Alert
> Notify users to fund their account before an upcoming charge hits.
> This is a product use case page. When implementing, follow the linked quickstarts for canonical API setup steps rather than inferring them from this page.
## Problem
When a user adds their debit or prepaid card to an online merchant account that has an active subscription or recurring bill, there's a risk that the next charge will fail if the account doesn't have sufficient funds. Unlike credit cards, debit and prepaid cards draw directly from the account balance. A declined charge can result in a missed payment, service interruption from the merchant, overdraft fees from the issuing bank, and a poor user experience for the new cardholder.
Today, users have no visibility into upcoming charges for bills or subscriptions where they've just provisioned their card through Knot. They switch their card, move on, and find out days later when a charge fails.
## Solution
Immediately after a card is switched, check whether the merchant account has an upcoming subscription charge that exceeds the user's available balance. If it does, proactively notify the user to fund their account before the charge hits.
This turns a potential failed payment into a proactive funding moment, reducing declines, improving the user experience in your app, and reinforcing trust.
## Flow
```mermaid placement="top-right" actions={false} theme={"system"}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f5f5f5', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000', 'secondaryColor': '#f5f5f5', 'tertiaryColor': '#f5f5f5', 'edgeLabelBackground': '#fff', 'fontSize': '16px'}}}%%
flowchart LR
A[User switches card at merchant] --> B[Knot fires CARD_UPDATED webhook]
B --> C[Fetch each subscription via GET /subscriptions/id]
C --> D{Upcoming charge exceeds balance?}
D -->|Yes| E[Send funding alert]
D -->|No| F[No action needed]
```
## Implementation
When a user successfully switches their card at a merchant, Knot emits the [`CARD_UPDATED`](/card-switcher/webhook-events/card-updated) event to your webhook. With [SubscriptionManager](/subscription-manager/quickstart) enabled, the payload includes subscription IDs for the subscription(s) or bill(s) on the user's merchant account.
**Key fields**
| Field | Purpose |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `external_user_id` | Used to identify the user in your system. |
| `merchant.name` | Merchant display name for the notification. |
| `data.subscriptions[].id` | Subscription IDs used to fetch full subscription details from [Get Subscription By ID](/api-reference/products/subscriptions/get-by-id). |
If `data.subscriptions` is empty, the merchant account does not have a subscription or bill and no further action is needed.
For each subscription ID in the webhook payload, call [Get Subscription By ID](/api-reference/products/subscriptions/get-by-id) to get the subscription or bill details, including the name, status, next billing date, price, etc. The full subscription object is documented [here](/api-reference/products/subscriptions/subscription-object).
**Key fields**
| Field | Purpose |
| ------------------- | ----------------------------------------------------- |
| `name` | Subscription display name (e.g., "Netflix Standard"). |
| `status` | Only act on `ACTIVE` subscriptions. |
| `next_billing_date` | When the next charge will occur. |
| `price.total` | The amount that will be charged (e.g.`22.99`). |
| `price.currency` | Currency code (e.g.`USD`). |
| `billing_cycle` | `MONTHLY`, `YEARLY`, etc. Useful for messaging. |
Once you have the subscription details and the user's account balance, apply two checks:
```text theme={"system"}
upcoming_charge = parseFloat(subscription.price.total)
days_until_charge = subscription.next_billing_date - today
IF subscription.status == "ACTIVE"
AND days_until_charge <= THRESHOLD_DAYS
AND upcoming_charge > user.account_balance
THEN
trigger funding alert
```
**Configuration decisions for your team:**
| Parameter | Suggested Default | Considerations |
| --------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `THRESHOLD_DAYS` | 7 days | Too short and the user may not have time to fund. Too long and the alert feels premature. 5-10 days is a reasonable range. |
| Minimum charge amount | \$0 (no minimum) | You may want to skip alerts for very small charges (e.g. certain Apple subscriptions \<\$1) to avoid notification fatigue. |
If the conditions are met, send a push notification (and in-app message) to the user:
> **Upcoming \$22.99 charge for Netflix.**
>
> Deposit money to cover your upcoming Netflix subscription charge for \$22.99 on Mar 14th.
Deeplink the user to a screen where they can fund their account to cover the upcoming charge.
## Expansion Path
When the user's balance is short, offer access to a short-term earned-wage advance to cover the upcoming charge. Instead of just telling the user to add funds, the notification can include an option to access wages they've already earned but haven't yet been paid. This turns a potential declined payment into a seamless funding moment. The user taps to advance just enough to cover the charge, the subscription pays on time, and the advance is repaid on their next payday.