# Events > The record of everything that happened in an app, and every event type. Source: https://abuna.app/docs/api/events Read the events that happened in your app, like a paid invoice, to keep your records in step with Abuna. Abuna records every event, and also sends it to your webhook URL if you set one. ## The event object An event has the same shape here and in a webhook body. A webhook for the event carries the same `id`. **Attributes** - `id` (string): Unique identifier for the event. Event IDs sort in the order the events happened. See [Event order](https://abuna.app/docs/api/events.md#order). - `type` (string): The event's [type](https://abuna.app/docs/api/events.md#types). - `environment` (string): `test` or `live`. - `created_at` (timestamp): When the event happened, in Unix seconds. - `data` (object): The event's data. Its fields depend on the [type](https://abuna.app/docs/api/events.md#types). **The event object** ```json { "created_at": 1794780106, "data": { "amount": 5000, "coupon_id": null, "credit": 0, "currency": "XAF", "discount": 0, "invoice_id": "OG3ZsOC7", "invoice_number": "ACME-000001", "kind": "period", "metadata": { "user_id": "42" }, "paid_at": 1794780106, "payment": { "amount": 5000, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "sandbox", "exchange_margin_bps": null, "exchange_rate": null, "exchange_rate_at": null, "fee": 100, "id": "tGfwt5dd", "marked_by_api_key_id": null, "marked_by_user_id": null, "message": null, "method_label": "Successful payment (test)", "net": null, "note": null, "original_amount": 5000, "original_currency": "XAF", "period_id": "0kYPFwxJ", "provider": "test", "provider_reference": "test_ff6aaf0182bd3f1148bd", "session_id": null, "status": "succeeded" }, "period_end": 1797372106, "period_id": "0kYPFwxJ", "period_start": 1794780106, "promotion_code_id": null, "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH" }, "environment": "test", "id": "01M7GKP458FZEMMQQ7VM7J4QK4", "type": "invoice.paid" } ``` ## List events `GET /v1/apps/{appID}/events` Lists the app's events, newest first, one page at a time. Each page continues with older events. See [Lists and filters](https://abuna.app/docs/lists-and-filters.md). **Query parameters** - `type` (string): Only events of this type, like `invoice.paid`. - `limit` (integer): How many events to return, from 1 to 100. Defaults to 50. - `cursor` (string): The `next_cursor` from the previous page. Send the same filters with it. **Response attributes** - `items` (array): The page's [events](https://abuna.app/docs/api/events.md#object), newest first. Empty when nothing matches. - `next_cursor` (string, nullable): Pass it as cursor to get the next, older page. It is null on the last page. Treat it as opaque. Returns `200`. A `limit` outside 1 to 100 returns `422` with code `invalid` and an `errors` item for `limit`. **GET /v1/apps/{appID}/events** cURL: ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid" \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=invoice.paid", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Response** ```json { "items": [ { "created_at": 1794780106, "data": { "amount": 5000, "coupon_id": null, "credit": 0, "currency": "XAF", "discount": 0, "invoice_id": "OG3ZsOC7", "invoice_number": "ACME-000001", "kind": "period", "metadata": { "user_id": "42" }, "paid_at": 1794780106, "payment": { "amount": 5000, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "sandbox", "exchange_margin_bps": null, "exchange_rate": null, "exchange_rate_at": null, "fee": 100, "id": "tGfwt5dd", "marked_by_api_key_id": null, "marked_by_user_id": null, "message": null, "method_label": "Successful payment (test)", "net": null, "note": null, "original_amount": 5000, "original_currency": "XAF", "period_id": "0kYPFwxJ", "provider": "test", "provider_reference": "test_ff6aaf0182bd3f1148bd", "session_id": null, "status": "succeeded" }, "period_end": 1797372106, "period_id": "0kYPFwxJ", "period_start": 1794780106, "promotion_code_id": null, "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH" }, "environment": "test", "id": "01M7GKP458FZEMMQQ7VM7J4QK4", "type": "invoice.paid" } ], "next_cursor": "MDFKOVpROEUxRjJHM0g0SjVLNk03TjhQOVE" } ``` ## Retrieve an event `GET /v1/apps/{appID}/events/{id}` Retrieves one event, in the same shape as its webhook body. Use it to fetch an event again by the `id` a webhook gave you. Returns the event. If the app has no event with that ID, returns `404` with code `not_found`. **GET /v1/apps/{appID}/events/{id}** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4 \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4", { headers: { Authorization: "Bearer sk_test_..." }, }); const event = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4", headers={"Authorization": "Bearer sk_test_..."}, ) event = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $event = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/events/01M7GKP458FZEMMQQ7VM7J4QK4", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var event map[string]any json.NewDecoder(res.Body).Decode(&event) ``` **Response** ```json { "created_at": 1794780106, "data": { "amount": 5000, "coupon_id": null, "credit": 0, "currency": "XAF", "discount": 0, "invoice_id": "OG3ZsOC7", "invoice_number": "ACME-000001", "kind": "period", "metadata": { "user_id": "42" }, "paid_at": 1794780106, "payment": { "amount": 5000, "app_id": "qhf83tDc", "created_at": 1794780106, "currency": "XAF", "driver": "sandbox", "exchange_margin_bps": null, "exchange_rate": null, "exchange_rate_at": null, "fee": 100, "id": "tGfwt5dd", "marked_by_api_key_id": null, "marked_by_user_id": null, "message": null, "method_label": "Successful payment (test)", "net": null, "note": null, "original_amount": 5000, "original_currency": "XAF", "period_id": "0kYPFwxJ", "provider": "test", "provider_reference": "test_ff6aaf0182bd3f1148bd", "session_id": null, "status": "succeeded" }, "period_end": 1797372106, "period_id": "0kYPFwxJ", "period_start": 1794780106, "promotion_code_id": null, "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH" }, "environment": "test", "id": "01M7GKP458FZEMMQQ7VM7J4QK4", "type": "invoice.paid" } ``` ## Event order Event IDs sort in the order the events happened. Compare them as plain strings: a later event's ID sorts after an earlier one's. `created_at` is in whole seconds, so the events of one change often share it. Order events by `id`, not by `created_at`. One change records several events at once. They come in this order: - **New subscription without a trial**: `subscription.created`, then `invoice.created`. - **Renewal**: `subscription.updated` if a scheduled downgrade starts with the new period, `subscription.renewed`, `subscription.past_due` if the new period has already started, then `invoice.created`. A renewal issued before the paid period ends sends `subscription.past_due` on its own later, when the paid period ends, if it is still unpaid then. - **Payment**: `customer.updated` if it gave the customer their first phone number, `subscription.updated` if it pays for an upgrade, `session.completed` if it was paid through a `payment` session or completes a `plan_change` session, `invoice.paid`, then on the first payment `subscription.paid` and the checkout's `session.completed`, and last `subscription.recovered` if the subscription was `past_due`. - **Deleting a customer**: `subscription.canceled` for each subscription the delete ended, then `customer.deleted`. ## Catch up on missed events If your server missed webhooks, list the events you didn't handle and handle them now. Start without `cursor`, then pass each page's `next_cursor` until it is `null`, or until you reach events created 5 minutes before the newest one you handled. An event can be listed a few seconds after a newer one, so skip the ones you already handled by `id` rather than stopping at the first. Handle what you collected oldest first. **Catch up on missed events** Node.js: ```javascript const base = "https://api.abuna.app/v1/apps/8ddhXCDW/events?limit=100"; const headers = { Authorization: "Bearer sk_test_..." }; const newestHandledAt = 1727600600; // created_at of the newest event you handled const stopAt = newestHandledAt - 5 * 60; const missed = []; let cursor = null; let done = false; while (!done) { const url = base + (cursor ? "&cursor=" + encodeURIComponent(cursor) : ""); const page = await (await fetch(url, { headers })).json(); for (const event of page.items) { if (event.created_at < stopAt) { done = true; break; } if (!(await alreadyHandled(event.id))) missed.push(event); } cursor = page.next_cursor; if (!cursor) done = true; } // Oldest first, in the order the events happened. for (const event of missed.reverse()) { await handle(event); } ``` Python: ```python import requests base = "https://api.abuna.app/v1/apps/8ddhXCDW/events" headers = {"Authorization": "Bearer sk_test_..."} newest_handled_at = 1727600600 # created_at of the newest event you handled stop_at = newest_handled_at - 5 * 60 missed = [] params = {"limit": 100} done = False while not done: page = requests.get(base, headers=headers, params=params).json() for event in page["items"]: if event["created_at"] < stop_at: done = True break if not already_handled(event["id"]): missed.append(event) if page["next_cursor"] is None: done = True params["cursor"] = page["next_cursor"] # Oldest first, in the order the events happened. for event in reversed(missed): handle(event) ``` ## Event types Each type below lists the fields in its `data`. IDs are strings, amounts are integers in the currency's smallest unit, and times are Unix seconds. Every event whose `data` has a `subscription_id` also has `subscription`: the full [subscription object](https://abuna.app/docs/api/subscriptions.md#object), as [Retrieve a subscription](https://abuna.app/docs/api/subscriptions.md#retrieve) returns it under `subscription`, as it stands right after the change the event reports. A session event whose `subscription_id` is null has no `subscription`. The lists below leave `subscription` out. The subscription includes `trial_ends_at`: the trial end in Unix seconds, or `null` without a trial. Its status is `trialing` during a free trial. Subscription, invoice, and plan offer events carry the subscription's [metadata](https://abuna.app/docs/api/subscriptions.md#metadata) when the event was recorded. Session events carry the session's own `metadata`, not the subscription's. Pass metadata on every session you create. Without it, session events carry `{}`. The lists below leave metadata out unless noted. ### session.completed A [session](https://abuna.app/docs/api/sessions.md) completed. A session completes at most once, and an expired session never completes. The `data` depends on the session's `type`. Every type has `session_id`, `type`, `subscription_id`, `customer_id`, `metadata` (the metadata you passed when you created the session), and `completed_at`. - `checkout` ([Create a checkout session](https://abuna.app/docs/api/sessions.md#create-checkout)): without a trial, the first payment succeeded and the subscription is now `active`. A trial checkout completes instead when the free trial starts, with `status: trialing` and no payment. Without a trial, `subscription.paid` is recorded at the same moment. Adds `price_id`, the subscription's price, and `updates`, the customer's [`updates`](https://abuna.app/docs/api/customers.md#object). When the checkout switched a [returning customer's](https://abuna.app/docs/api/sessions.md#returning-customers) plan instead, the session completed once the switch was confirmed, or paid for an upgrade. `subscription_id` is their existing subscription, and the data adds the `plan_change` fields below instead of `updates`. - `payment` ([Create a payment session](https://abuna.app/docs/api/sessions.md#create-payment)): the invoice was paid through the session. `invoice.paid` is also sent. Adds `invoice_id`. - `plan_change` ([Create a plan change session](https://abuna.app/docs/api/sessions.md#create-plan-change)): the customer confirmed the change, and paid it if it was an upgrade with something to pay. Adds the fields below. - `cancel` ([Create a cancel session](https://abuna.app/docs/api/sessions.md#create-cancel)): the customer confirmed the cancel, scheduled or immediate. `subscription.updated` (scheduled) or `subscription.canceled` (immediate) is also sent. Adds the fields below. - `portal` ([Create a portal session](https://abuna.app/docs/api/sessions.md#create-portal)): the customer opened the customer portal for the first time. It doesn't mean they changed anything. What they do there sends its own events, like `subscription.updated`, `subscription.canceled`, `invoice.paid`, and `customer.updated`. Adds nothing. **plan_change data, and a checkout's switch, adds** - `plan_offer_id` (string): The plan offer behind the session. - `previous_price_id` (string): The price before the change. - `price_id` (string): The new price. - `direction` (string): `upgrade` or `downgrade`. - `effective_at` (timestamp): When the new price starts. For a downgrade, or an upgrade at the next renewal, the end of the paid period: `subscription.updated` fires with the price change then. **cancel data adds** - `cancel_at` (timestamp, nullable): When the subscription ends. `subscription.canceled` fires then. Null when it ended right away. - `immediate` (boolean): `true` when the subscription ended right away. ### session.expired An open session ran out at its `expires_at`, or you [expired it](https://abuna.app/docs/api/sessions.md#expire). Abuna doesn't expire a checkout session on its own while its payment is pending. A `pending` subscription a checkout session started stays, and ends with `checkout_expired` if it isn't paid in time. A `payment` session also expires when its invoice is paid another way, voided, or its subscription ends. A `plan_change` session also expires when its offer is replaced, canceled, or expires, or when an upgrade it started lapses unpaid. A `checkout` session that offered a switch expires the same way, instead of after 24 hours. A `cancel` session expires 24 hours after creation if the customer doesn't confirm, and a `portal` session 1 hour after creation if nobody opens it. See [Session types](https://abuna.app/docs/api/sessions.md#types). **data** - `session_id` (string): The session. - `type` (string): The session's type: `checkout`, `payment`, `plan_change`, `cancel`, or `portal`. - `subscription_id` (string, nullable): The subscription the session started or acts on. For checkout, null if the customer didn't get that far. - `customer_id` (string, nullable): The customer you passed, or the one the customer's details created. Null if neither. - `price_id` (string, nullable): The session's price, or null for payment, cancel, and portal sessions. - `invoice_id` (string, nullable): The payment session's invoice, or null for other types. - `plan_offer_id` (string, nullable): The offer of a plan_change session, or of a checkout session that offered a switch. Null otherwise. - `metadata` (object): The metadata you passed when you created the session. - `expired_at` (timestamp): When the session expired. **session.expired data** ```json { "customer_id": "GzeUZeSV", "expired_at": 1794780106, "invoice_id": null, "metadata": { "user_id": "42" }, "plan_offer_id": null, "price_id": null, "session_id": "XYKz5u9G", "subscription": { "activated_at": 1794780106, "app_id": "qhf83tDc", "cancel_at": null, "cancel_at_period_end": false, "canceled_at": null, "created_at": 1794780106, "current_period_end": 1797372106, "current_period_start": 1794780106, "customer_id": "GzeUZeSV", "discount": null, "ended_reason": null, "id": "wTiODxvH", "manage_token": "ac78d36db5c13e5f1bcbb67ece2ee29137a0", "metadata": { "user_id": "42" }, "price_id": "IaFQHLTL", "starts_at": 1794780106, "status": "active", "trial_ends_at": null }, "subscription_id": "wTiODxvH", "type": "cancel" } ``` ### subscription.created A subscription was created, through the API, a checkout session, or a checkout link. It is `trialing` with an eligible free trial, or `pending` without one. **data** - `subscription_id` (string): The new subscription. - `customer_id` (string): Its customer. - `price_id` (string): Its price. - `period_id` (string): Its free trial period, or first billing period without a trial. ### subscription.paid The first billing period was paid and the subscription is now `active`. After a free trial, this is the payment of the first invoice, whenever the customer pays it. A trial start doesn't send it. Later payments send `invoice.paid`, and `subscription.recovered` when they bring a `past_due` subscription back to `active`. **data** - `subscription_id` (string): The subscription. - `customer_id` (string): Its customer. - `price_id` (string): Its price. - `period_id` (string): The first billing period that was paid. - `activated_at` (timestamp): When the subscription started: the trial start, or the first payment without a trial. ### subscription.trial_ending A free trial is ending. Abuna sends this event at your app's normal renewal reminder lead time. Use `data.subscription.trial_ends_at` for the end date, in Unix seconds. The event carries the subscription and its metadata, as described above. See [Free trials](https://abuna.app/docs/guides/trials.md). A webhook URL added from now on receives this event by default. A URL you set up before free trials existed doesn't receive it until you turn it on: a team owner opens **Webhooks** in the dashboard, edits **Events** and picks it. ### subscription.renewed After a trial, the first paid period starts at `trial_ends_at`, even when paid early. Abuna issued the next billing period and its invoice. That happens before the paid period or trial ends, as many days ahead as the app's [`renewal_lead_days`](https://abuna.app/docs/api/apps.md#object) says (3 by default), or when it ends with `0`. The new period starts when the paid one ends, and the customer can pay it from now. If it is still unpaid when the paid period ends, `subscription.past_due` follows then. **data** - `subscription_id` (string): The subscription. - `period_id` (string): The new billing period. - `amount` (integer): The amount due for the new period. - `currency` (string): `XAF`, `XOF` or `USD`. ### subscription.past_due The paid period or trial ended and the next period isn't paid, so the subscription is now unpaid (`past_due`). A renewal paid before the paid period ends never sends it. Keep the customer's access while it is `past_due`. If the period isn't paid by its pay-by date, `subscription.canceled` follows with reason `non_payment`. **data** - `subscription_id` (string): The subscription. - `metadata` (object): The subscription's metadata. ### subscription.recovered The invoice of a `past_due` subscription was paid, so it is `active` again. It comes right after `invoice.paid`. It also comes when a payment that arrives after a cancel for non-payment brings the subscription back; see [Payments that arrive late](https://abuna.app/docs/api/subscriptions.md#late-payments). The `data` is the same as `subscription.past_due`. ### subscription.updated Something was scheduled or changed on a current subscription, including a trial. It fires when a cancel at the end of the trial or paid period is scheduled or undone, when the price changes (an upgrade takes effect, or a scheduled downgrade starts), when a downgrade, or an upgrade at the next renewal, is scheduled or undone, when an upgrade waiting for payment lapses, and when a new change clears an earlier one. For a scheduled cancel, `subscription.canceled` follows when it ends. See [Changing plan](https://abuna.app/docs/api/subscriptions.md#changing-plan). **data** - `subscription_id` (string): The subscription. - `price_id` (string): The price the subscription is on now. - `cancel_at` (timestamp, nullable): When the subscription will end, if a cancel is scheduled. Null otherwise. - `cancel_at_period_end` (boolean): `true` while a cancel is scheduled for the end of the paid period, `false` otherwise. - `scheduled_price_change` (object, nullable): The downgrade, or upgrade at the next renewal, scheduled for the end of the paid period. Null when none is. - `price_id` (string): The price the subscription moves to. - `effective_at` (timestamp): When it moves. - `change` (object): What happened to the price. Present only when the price changed, or a downgrade or an upgrade at the next renewal was scheduled or undone. A lapsed upgrade, a cancel at the end of the period, and an upgrade that starts waiting for payment have none. - `type` (string): `price_changed`, `downgrade_scheduled`, `downgrade_undone`, `upgrade_scheduled`, or `upgrade_undone`. - `old_price_id` (string): The price before. - `new_price_id` (string): The new price, or the scheduled one. - `effective_at` (timestamp): When the change took effect, or when the scheduled one will. - `updated_by` (string): `merchant` when you changed it, or `customer` when they changed it in the customer portal or switched plan at a checkout. When a plan change is carried out later (a paid upgrade, a downgrade that starts, an upgrade that lapses), it is whoever asked for it: `customer` from the portal or a checkout, or `merchant` when they confirmed a change you sent them to. ### subscription.canceled The subscription ended. It fires when the subscription really ends: right away for a cancel now, or at the end of the paid period for a scheduled cancel. Scheduling a cancel sends `subscription.updated` instead. The `subscription` in the `data` has `ended_reason` `unpaid` for `non_payment` and `checkout_expired`, and `canceled` for the others. **data** - `subscription_id` (string): The subscription. - `reason` (string): Why it ended: `merchant` (you canceled it), `customer` (they canceled in the customer portal), `non_payment` (a renewal passed its pay-by date), or `checkout_expired` (the first period was never paid). A scheduled cancel that ends keeps who scheduled it, `merchant` or `customer`. ### plan_offer.created A [plan change session](https://abuna.app/docs/api/sessions.md#create-plan-change) made a plan offer, a checkout offered a [returning customer a switch](https://abuna.app/docs/api/sessions.md#checkout-switch), or you offered a change from the dashboard and Abuna sent the customer the link. A plan change session sends no email; a checkout switch sends its confirmation link by email only. Resending the link from the dashboard doesn't fire it again. The four `plan_offer` events share the same `data`. **data** - `offer_id` (string): The offer. - `subscription_id` (string): The subscription. - `price_id` (string): The price offered. - `expires_at` (timestamp): When the offer stops working. ### plan_offer.confirmed The customer accepted the offer. A downgrade, or an upgrade at the next renewal, is now scheduled, or an upgrade is applied or waiting for payment. `subscription.updated` fires when the price changes or the change is scheduled. ### plan_offer.canceled The offer stopped before the customer accepted it. The `data` adds `reason`: `merchant` when you canceled it, or `replaced` when a new offer or the customer's own plan change took its place, or the subscription was canceled. A cancel records `plan_offer.canceled` just before `subscription.canceled`, so it has the lower event `id`. ### plan_offer.expired The offer reached its `expires_at` without being accepted. ### invoice.created Abuna issued an invoice for a new billing period, or for an upgrade. An upgrade waiting for payment gets its period dates when it is paid, and `invoice.paid` carries them. **data** - `invoice_id` (string): The invoice. - `invoice_number` (string): Its number. - `subscription_id` (string): Its subscription. - `period_id` (string): The billing period it bills. - `kind` (string): `period` for a billing period, or `plan_change` for the first period of an upgrade. - `amount` (integer): The amount due. - `credit` (integer): The unused time of the current period taken off the new price. `0` on a `period` invoice. - `discount` (integer): What the invoice's coupon took off it. `0` without one. `amount` is already after it. See [the invoice object](https://abuna.app/docs/api/invoices-and-payments.md#invoice-object). - `coupon_id` (string, nullable): The coupon that took the discount off. Null without one. - `promotion_code_id` (string, nullable): The promotion code that brought the coupon. Null when you applied the coupon directly, without a code. - `currency` (string): `XAF`, `XOF` or `USD`. - `period_start` (timestamp): When the period starts. - `period_end` (timestamp): When the period ends. ### invoice.paid An invoice was paid. A renewal paid before its period starts is still for that period: `period_start` doesn't move. An invoice that was void can also become paid, when a payment the customer approved before it was voided goes through; see [Payments that arrive late](https://abuna.app/docs/api/subscriptions.md#late-payments). The `data` has every `invoice.created` field, plus two. Its `amount` and `currency` stay the invoice's, in the price's currency. **data** - `paid_at` (timestamp): When it was paid. - `payment` (object): The payment that paid the invoice, as the [payment object](https://abuna.app/docs/api/invoices-and-payments.md#payment-object). Its `amount` and `currency` are what the customer was charged, in FCFA for mobile money. When the invoice was in another currency, `original_amount`, `original_currency` and `exchange_rate` show the conversion. ### invoice.payment_failed A payment on an invoice failed. The invoice stays open, so the customer can try again before the pay-by date. Some payments are reported as failed before the provider has confirmed how they ended, for example when it doesn't answer in time. Such a payment can still be paid later, usually within 7 days of when it started. A payment that failed for a stated reason, like `insufficient_funds`, stays failed unless the provider later reports it paid. Whenever a failed payment is paid, you get [`invoice.paid`](https://abuna.app/docs/api/events.md#invoice-paid), and the invoice is `paid`. Treat `invoice.paid` as the final word: don't refund the customer or cut off their access on `invoice.payment_failed` alone. **data** - `subscription_id` (string): The subscription. - `period_id` (string): The billing period. - `invoice_id` (string): The invoice. - `invoice_number` (string): Its number. - `provider_reference` (string): The provider's ID for the charge. Empty if it gave none. - `failure` (string): Why it failed, with the same [codes](https://abuna.app/docs/errors.md) as a charge refused with `402`, like `insufficient_funds`. It is `payment_declined` when the provider gave no reason. - `message` (string): A short note about the failure for people to read. Don't parse it, since its wording can change. Branch on `failure`. Empty when there's no note. - `payment` (object): The payment that failed, as the [payment object](https://abuna.app/docs/api/invoices-and-payments.md#payment-object), with the amount it tried to charge. ### customer.updated A customer's name, email, phone number, or metadata changed. It is also sent when a customer with no phone number pays for the first time: their `phone_number` is now the number that paid, and `updated_by` is `customer`. **data** - `customer_id` (string): The customer. - `name` (string, nullable): Their name now. - `email` (string): Their email address now. - `phone_number` (string, nullable): Their phone number now. Null until their first payment if they came through checkout. - `metadata` (object): The customer's [metadata](https://abuna.app/docs/api/customers.md#object). - `updated_by` (string): `merchant` when you changed it, or `customer` when they changed it in the customer portal or their first payment gave them a phone number. - `updates` (object): The customer's [`updates`](https://abuna.app/docs/api/customers.md#object) now. ### customer.updates_changed A customer's Telegram or WhatsApp status changed. It happens when the customer subscribes through a checkout, connects a chat app on the checkout's payment step or in their customer portal, turns it on (in Telegram, or by confirming their WhatsApp number with a code), stops it by sending "stop" in the chat, turns it off in their customer portal, or, for WhatsApp, has a number that can't get messages. A change you make to your app's chat app settings doesn't send it. Each change sends one event, and a status that stays the same sends none. **data** - `customer_id` (string): The customer. - `channel` (string): The chat app whose status changed: `telegram` or `whatsapp`. - `status` (string): The status now: `off`, `active`, `stopped`, or, for Telegram, `pending`, and, for WhatsApp, `failed`. - `previous_status` (string): The status before. - `updates` (object): The customer's [`updates`](https://abuna.app/docs/api/customers.md#object) now. **customer.updates_changed data** ```json { "customer_id": "Cu5tM8rA", "channel": "telegram", "status": "active", "previous_status": "pending", "updates": { "channel": "telegram", "email": { "status": "active" }, "telegram": { "status": "active", "connected_at": 1727600300, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } } } ``` List these events to see how many customers turned a chat app on: **GET /v1/apps/{appID}/events** cURL: ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed" \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/events?type=customer.updates_changed", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` ### customer.deleted You [deleted a customer](https://abuna.app/docs/api/customers.md#delete). Their subscriptions have ended and their personal details are erased, so the event carries none of them. When you get it, delete your own copy of the customer's details. It comes after the `subscription.canceled` events of that delete. Deleting the same customer again sends nothing. **data** - `customer_id` (string): The customer. - `deleted_by` (string): `merchant`: you deleted the customer, with your secret key or in the dashboard. It is the only value today. **customer.deleted data** ```json { "customer_id": "Cu5tM8rA", "deleted_by": "merchant" } ``` ### price_change.scheduled You [scheduled a new amount](https://abuna.app/docs/api/prices.md#change) for a price, or replaced the one that was pending. The three `price_change` events share the same `data`. **data** - `price_change_id` (string): The change. - `price_id` (string): The price. - `amount` (integer): The new amount. - `previous_amount` (integer): The amount before the change. - `currency` (string): `XAF`, `XOF` or `USD`. - `effective_at` (timestamp): Midnight at the start of the day the new amount applies from, in timezone. - `timezone` (string): Your app's time zone, like `Africa/Douala`. It is the app's [`timezone`](https://abuna.app/docs/api/apps.md#object). - `keep_current_subscribers` (boolean): `true` when everyone subscribed on that day keeps the old amount. ### price_change.canceled A pending change stopped before its day. The `data` adds `reason`: `merchant` when you canceled it, or `replaced` when you scheduled a new change in its place. A replacement also sends `price_change.scheduled`. ### price_change.applied The price's amount switched to the new one on its `effective_at`. The event arrives within about a minute of that time. From then on, checkouts and new subscriptions pay it. Current subscribers move to it at their next renewal, unless `keep_current_subscribers` is `true`. ### notification.captured Test mode only. Abuna wrote a message to a Test customer and kept a copy here. Most Test messages are not sent; `sent` says which ones were. This event never goes to your webhook URL. **data** - `customer_id` (string): The customer. Left out for `profile_code`, because the person may not be a customer yet. - `kind` (string): What the message is about. See [customer message kinds](https://abuna.app/docs/api/notices.md#object). One more kind shows up only here: `profile_code`, the code for a customer's saved details at checkout. - `channel` (string): `email`, `telegram`, or `whatsapp`. - `recipient` (string): The email address, WhatsApp number, or Telegram chat it went to, or would have gone to. - `subject` (string): The subject line. For a code email, it holds the code. - `text` (string): The message, as plain text. - `sent` (boolean): `true` for the three email codes Test sends as Live does: `trial_email_code`, `email_code`, and `profile_code`. `false` for every other message, which was not sent.