Customer notifications

Abuna tells your customers about their subscription for you: what to pay, what they paid, and when their plan ends. Every notice goes by email. It also goes to Telegram if the customer connected Telegram. You don't need to write or send any of these messages yourself.

What customers receive

Each notice has a kind, shown here in parentheses. The Notices API uses the same names.

• Subscription started (subscription_started): when a subscription is created. It asks the customer to pay for the first period and links to the pay link.
• Payment received (payment_received): a receipt, after every successful payment. When the payment puts an upgrade in force, the receipt also says the plan changed.
• Payment failed (payment_failed): when a payment fails after the customer left the pay page, for example when they never approved it on their phone, with the reason. A decline the customer sees on the pay page sends nothing. At most one goes out an hour for the same invoice.
• Renewal coming up (renewal_upcoming): 3 days before a paid period ends, with the amount the renewal will cost. With a downgrade scheduled, that is the new price.
• Subscription renewed (subscription_renewed): when a new period starts, with the amount due and a pay link.
• Payment overdue (payment_overdue): once a day while a renewal is unpaid.
• Last reminder (payment_final_notice): 1 day before an unpaid subscription is canceled, or halfway through with 1 day to pay.
• Subscription ending (subscription_cancel_scheduled): when a cancel is set for the end of the paid period, whether you or the customer set it. It says the date the subscription ends and how to keep it.
• Subscription continues (subscription_cancel_undone): when a scheduled cancel is undone. One short confirmation.
• Subscription canceled (subscription_canceled): when the subscription ends. That is right away when you or the customer cancel now, at the end of the paid period for a scheduled cancel, or when it ends because it wasn't paid. A first checkout that's never paid ends without a notice.
• Plan change offered (plan_change_offered): when you offer the customer another plan from the dashboard, and each time you resend it. It links to the page where they accept it. A Change plan session doesn't send it.
• Plan upgraded (plan_upgraded): when an upgrade takes effect, with the new plan and the new billing date. If the new period still has to be paid, it has the amount due and the pay link. An upgrade that takes effect when the customer pays sends the receipt instead, so they get one message.
• Upgrade to pay (plan_upgrade_due): when an upgrade waits for the customer to pay the rest of the new plan, with the amount, the date to pay by, and the pay link. It says the customer stays on their plan if they don't pay, and, if the upgrade replaced a scheduled cancel, that the subscription still ends on its date. Nothing is sent when the upgrade lapses.
• Downgrade scheduled (plan_downgrade_scheduled): when a downgrade is set for the end of the paid period, with the new plan and the date it starts.
• Downgrade undone (plan_downgrade_undone): when a scheduled downgrade is undone, whether you or the customer undid it. It says the customer keeps their plan, with the next billing date and amount.
• Price change (price_change_scheduled): when you schedule a new amount for a price and current subscribers will move to it, with the new amount and the date it first applies to them. Customers who subscribe while the change is pending get it when they subscribe.
• Price change canceled (price_change_canceled): when you cancel that change, or replace it with one that keeps current subscribers on the old amount. It says their price stays the same.
• Contact details changed (contact_changed): when the customer changes their email or phone number in the customer portal. It goes to their old email address and their connected Telegram chat, never to the new address.
• Subscription links (portal_links): when a customer asks for links to their subscriptions on your page. It goes by email only, at most once every 5 minutes.

Emails come from <your app's name> via Abuna, and when the customer replies, the reply goes to your support email. Each email ends with your support email or support URL, a link to the customer portal, and, until the customer connects Telegram, a link to get the same updates there. Emails about a subscription that has ended, and subscription links, leave out the portal and Telegram links. When you set your own terms, the footer links them. On the Free plan, the footer also says Billed with Abuna. Set your support email and terms in the dashboard, under Settings, General, Customer support.

Dates and times show in your app's time zone. New apps start on Cameroon time for XAF and Côte d'Ivoire time for XOF. Change it under Settings, General, Time zone.

When reminders go out

Renewals are billed in advance. When a period ends, Abuna starts the next one and sends the invoice. The customer then has your app's Days to pay, 1 to 14 days, before the subscription is canceled. New apps start at 3 days. You set it in Settings, General, Time to pay.

1. 3 days before a paid period ends, the customer gets a renewal reminder.
2. When the new period starts, they get the renewal invoice.
3. Each day after that, while it's unpaid, they get an overdue reminder.
4. 1 day before the cancel date, they get a last reminder instead.
5. If it's still unpaid on the cancel date, the subscription is canceled and they're told.

Abuna skips a reminder that would arrive within an hour of the invoice or a receipt, so customers don't get the same message twice. Every unpaid invoice gets at least one reminder before the cancel: with 1 day to pay, the last reminder goes out halfway through, 12 hours before the cancel. A reminder that's no longer true, because the customer paid or the subscription ended, is withdrawn before it goes out.

While a Live app can't take payments, for example with no payment provider connected, renewal invoices and payment reminders wait, and nobody is canceled for not paying. Once the app takes payments again, the customer gets the reminder that's due then, with the pay link.

Telegram

Each email has a Get subscription updates on Telegram link. When the customer opens it and taps Start, Abuna's bot connects their chat. From then on, each notice goes to both their email and their Telegram. Subscription links still go by email only.

• Each link works once. Once a chat is connected, emails stop carrying the link, so a forwarded email can't move the customer's notices to someone else's chat. The customer portal still shows it.
• Only private chats can connect. A group chat would show one customer's pay links to everyone in it.
• If the customer connects another Telegram account, notices move to it, and the old chat is told.
• The customer can send /stop to the bot at any time. Notices then go by email only, and any still waiting for Telegram are withdrawn.

Test mode

Test customers often have real email addresses and Telegram chats, so Test mode never sends a notice. Abuna records each one as a notification.captured event instead, with the subject and text it would have sent. These events don't go to your webhook endpoint. List them to check your flow:

curl "https://api.abuna.app/v1/apps/01J9ZQ4Y7R3T6V8W2X5B1C0DEF/events?type=notification.captured" \
  -H "Authorization: Bearer sk_test_..."

{
  "id": "01J9ZQ8E1F2G3H4J5K6M7N8P9Q",
  "event_type": "notification.captured",
  "payload": {
    "customer_id": "01J9ZQ6A1B2C3D4E5F6G7H8J9K",
    "kind": "payment_received",
    "channel": "email",
    "recipient": "ana@example.com",
    "subject": "Receipt from My store: FCFA 5,000 paid",
    "text": "...",
    "sent": false
  },
  "created_at": 1727600000
}

Check what was sent

In Live mode, list your notices with GET/v1/apps/{appID}/notices. Filter by subscription_id or by status: pending, sending, sent, failed, or withdrawn. In Test mode the list is always empty.

curl "https://api.abuna.app/v1/apps/01J9ZQ4Y7R3T6V8W2X5B1C0DEF/notices?subscription_id=01J9ZQ6M1N2P3Q4R5S6T7V8W9X" \
  -H "Authorization: Bearer sk_live_..."

If a notice can't be sent, Abuna tries up to 5 times over about 40 minutes, then marks it failed. See Notices for each field.

Emails to your team

In Live mode, your team members get their own emails when a subscription starts, a payment is received, a payment fails, a subscription is canceled, or a customer changes plan. Scheduling a cancel for the end of the paid period, or undoing it, counts as a cancel. A plan change is an upgrade taking effect, or a downgrade scheduled or undone. Each member picks which ones they want, and whether they come right away or once a day, under Notifications in their profile. A first payment or a paid upgrade is one email, not two.