# Subscriptions > Start, list, read, update, cancel, keep and change the plan of a customer's subscription. Source: https://abuna.app/docs/api/subscriptions Use subscriptions to bill a customer for a price, one billing period at a time. A subscription starts `trialing` during a free trial, or `pending` without one, becomes `active` when the customer pays the first period, is unpaid (`past_due`) while a renewal waits for payment, and ends `canceled`. See [Statuses](https://abuna.app/docs/api/subscriptions.md#statuses). ## The subscription object **Attributes** - `id` (string): Unique identifier for the subscription. - `app_id` (string): The app the subscription belongs to. - `customer_id` (string): The customer who pays. - `price_id` (string): The price the customer pays. - `status` (string): `trialing` during a free trial. Without a trial, `pending` until the first period is paid, then `active`. `past_due` when a paid period has ended and its renewal isn't paid yet, then `active` again once it is. `canceled` once it ends. See [Statuses](https://abuna.app/docs/api/subscriptions.md#statuses). - `starts_at` (timestamp): When the subscription starts, including its free trial if any, in Unix seconds. - `activated_at` (timestamp, nullable): When the trial started, or the first period was paid without a trial. - `trial_ends_at` (timestamp, nullable): When the free trial ends, in Unix seconds. Null for a subscription without a trial. - `canceled_at` (timestamp, nullable): When the subscription was canceled. - `cancel_at` (timestamp, nullable): When the subscription will end, if a cancel is scheduled for the end of the paid period or trial. Null otherwise. It stays `active` or `trialing` until then. - `cancel_at_period_end` (boolean): `true` while a cancel is scheduled for the end of the paid period or trial, so `cancel_at` is set. `false` otherwise, including once the subscription has ended. - `current_period_start` (timestamp, nullable): When the newest paid period or free trial started, in Unix seconds. An early-paid renewal can start in the future. Null until the first payment or trial. It stays set after the subscription ends. - `current_period_end` (timestamp, nullable): When the newest paid period or free trial ends, in Unix seconds. Null until the first payment or trial. It stays set after the subscription ends. - `ended_reason` (string, nullable): Why the subscription ended. `canceled` when you or the customer canceled it, now or at the end of the paid period. `unpaid` when a billing period wasn't paid by its pay-by date, including a first period never paid. Null unless `status` is `canceled`. - `metadata` (object): Your own keys and values. `{}` when there are none. A subscription started by a [checkout session](https://abuna.app/docs/api/sessions.md#create-checkout) gets the session's. See [Metadata](https://abuna.app/docs/api/subscriptions.md#metadata). - `created_at` (timestamp): When the subscription was created, in Unix seconds. - `manage_token` (string): The token in the customer portal link. Anyone with the link can see and cancel the subscription, so keep it private. - `discount` (object, nullable): The coupon the subscription holds. Null without one. See [Run a sale with promotion codes](https://abuna.app/docs/guides/promotion-codes.md). - `coupon` (object): The [coupon](https://abuna.app/docs/api/coupons.md#object). - `promotion_code` (string, nullable): The ID of the promotion code that brought the coupon. Null when you applied the coupon directly, without a code. - `start` (timestamp): When the discount started, in Unix seconds. - `end` (timestamp, nullable): For `repeating`, when the discount stops. Null for `once` and `forever`. **The subscription object** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## Create a subscription `POST /v1/apps/{appID}/subscriptions` Without a trial, starts a `pending` subscription and its first [billing period](https://abuna.app/docs/api/invoices-and-payments.md#period-object), which starts now. Abuna issues the period's invoice and sends the customer a message with its pay link. To have the customer sign up and pay on the checkout page instead, use [Create a checkout session](https://abuna.app/docs/api/sessions.md#create-checkout). With an eligible trial, starts `trialing` instead, without an immediate charge. The first paid period starts at `trial_ends_at`. See [Free trials](https://abuna.app/docs/guides/trials.md) for billing, eligibility and webhooks. **Parameters** - `customer_id` (string, required): The customer to bill. - `price_id` (string, required): The price to bill them. - `trial_days` (integer): Override the price's trial with 1 to 365 days. Send `0` to disable it. Omit it to use the price's default. Only one trial per customer, product and app; a used trial falls back to normal billing without an error. - `discounts` (array): A discount for this subscription: one entry with `coupon` or `promotion_code`, by ID, not both. A discount that can't be used returns `422` with code `coupon_invalid` for `discounts`. See [Run a sale with promotion codes](https://abuna.app/docs/guides/promotion-codes.md). - `metadata` (object): Your own keys and values. See [Metadata](https://abuna.app/docs/api/subscriptions.md#metadata) for the limits. Returns an object with the `subscription` and its first period (free trial or billed), `period`, with status `201`. If the app has no customer or price with that ID, returns `404` with code `not_found` and an `errors` item for `customer_id` or `price_id`. If the price is archived, returns `410` with code `price_archived`. If a Live app can't take payments yet, returns `422` with code `not_accepting_payments`. If the customer would pass the Live subscriber limit of your team's plan, returns `403` with code `plan_limit`. **POST /v1/apps/{appID}/subscriptions** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ customer_id: "Cu5tM8rA", price_id: "Zt6YbN3q" }), }); const result = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions", headers={"Authorization": "Bearer sk_test_..."}, json={"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}, ) result = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["customer_id" => "Cu5tM8rA", "price_id" => "Zt6YbN3q"]), CURLOPT_RETURNTRANSFER => true, ]); $result = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]string{"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) ``` **Response** ```json { "subscription": { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "pending", "starts_at": 1727600000, "activated_at": null, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": null, "current_period_end": null, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null }, "period": { "id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "price_id": "Zt6YbN3q", "pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "starts_at": 1727600000, "ends_at": 1730192000, "period_index": 0, "grace_period_ends_at": 1727686400, "paid_at": null, "paused_at": null, "in_force": true, "created_at": 1727600000 } } ``` ## List subscriptions `GET /v1/apps/{appID}/subscriptions` Lists the app's subscriptions, newest first, one page at a time. Each item has the subscription's fields, including `cancel_at`, `current_period_start`, `current_period_end`, `ended_reason` and `metadata`, without `app_id` and `manage_token`, plus three more. **Query parameters** - `status` (string): Returns only subscriptions with this status: `pending`, `trialing`, `active`, `past_due` or `canceled`. - `customer_id` (string): Returns only this customer's subscriptions. - `email` (string): Returns only subscriptions whose customer's email contains this text. Case doesn't matter. - `limit` (integer): How many subscriptions to return, from 1 to 100. Defaults to 50. - `cursor` (string): The `next_cursor` from the previous page. Send the same filters with it. **Extra attributes** - `customer` (object): Who pays. - `name` (string, nullable): The customer's name. - `email` (string): The customer's email address. - `price` (object): What they pay. - `name` (string): The price's name. - `amount` (integer): The amount for each period, in the currency's smallest unit. - `currency` (string): `XAF`, `XOF` or `USD`. - `interval` (string): `day`, `week`, `month` or `year`. - `interval_count` (integer): How many intervals make up one period. - `next_payment_at` (timestamp, nullable): When the next payment is due. While the latest period is unpaid, it is that period's start, even if that is in the past. Once it is paid, it is the next period's start. Null once canceled, and null while a cancel is scheduled. Returns `items` and `next_cursor`, as described in [Lists and filters](https://abuna.app/docs/lists-and-filters.md). An unknown `status` or a `limit` outside 1 to 100 returns `422` with code `invalid`. **GET /v1/apps/{appID}/subscriptions** cURL: ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", 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/subscriptions?status=active&customer_id=Cu5tM8rA", 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": [ { "id": "x9QbL2sK", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "customer": { "name": "Jane Doe", "email": "jane@example.com" }, "price": { "name": "Monthly", "amount": 5000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "next_payment_at": 1730192000 } ], "next_cursor": null } ``` ## Retrieve a subscription `GET /v1/apps/{appID}/subscriptions/{id}` Retrieves a subscription with its customer, price, billing periods and payments. **Response attributes** - `subscription` (object): The subscription object. - `subscription_page_url` (string): The customer portal link, where the customer sees and cancels the subscription. - `customer` (object): The [customer object](https://abuna.app/docs/api/customers.md#object), plus `telegram_connected`. - `price` (object): The [price object](https://abuna.app/docs/api/prices.md#object). - `periods` (array): Every billing period in force, oldest first. An upgrade's period waiting for payment, or one that lapsed, isn't listed. The waiting one shows in `pending_change`, and its invoice is still in the [invoice list](https://abuna.app/docs/api/invoices-and-payments.md#list). - `id` (string): The billing period's ID. - `starts_at` (timestamp): When the period starts. - `ends_at` (timestamp): When the period ends. - `grace_period_ends_at` (timestamp): The pay-by date. - `paid_at` (timestamp, nullable): When the period was paid. - `pay_url` (string): The pay link for the period. - `invoice` (object, nullable): The period's [invoice object](https://abuna.app/docs/api/invoices-and-payments.md#invoice-object). - `invoice_url` (string, nullable): A link to the invoice page. It expires after 7 days. - `payments` (array): Every [payment](https://abuna.app/docs/api/invoices-and-payments.md#payment-object) on the subscription, newest first. - `pending_change` (object, nullable): The plan change waiting to happen: an upgrade waiting for payment, or a downgrade, or an upgrade at the next renewal, scheduled for the end of the paid period. Null when there is none. A scheduled cancel shows in `cancel_at` instead. - `id` (string): The plan change. - `type` (string): `upgrade` or `downgrade`. - `price` (object): The new price: `id`, `name`, `amount`, `currency`, `interval` and `interval_count`. - `requested_by` (string): `customer` when they chose it in the customer portal or at a checkout, or `merchant` when they confirmed a change you sent them to. - `created_at` (timestamp): When the change was requested. - `amount_due` (integer, nullable): What the customer pays to switch now. Null for a downgrade, and 0 for an upgrade at the next renewal. - `credit` (integer, nullable): The unused time of the current period taken off the new price. Null for a downgrade, and 0 for an upgrade at the next renewal. - `expires_at` (timestamp, nullable): If the upgrade isn't paid by then, it lapses and the current plan carries on. Null for a scheduled change. - `pay_url` (string, nullable): The pay link for the upgrade. Null for a scheduled change. - `effective_at` (timestamp, nullable): When a scheduled change starts. Null for an upgrade waiting for payment. - `plan_offer` (object, nullable): The [plan change](https://abuna.app/docs/api/sessions.md#create-plan-change) waiting for the customer to confirm, or null. It is null once it is past its `expires_at`. - `id` (string): The offer. - `price` (object): The price offered: `id`, `name`, `amount`, `currency`, `interval` and `interval_count`. - `status` (string): Always `pending` here. - `url` (string): The page where the customer confirms the change. - `created_at` (timestamp): When the offer was made. - `expires_at` (timestamp): When the offer runs out if the customer hasn't confirmed it. - `sent_at` (timestamp, nullable): When Abuna sent the customer the link, or null when it didn't send one. - `plan_changes` (array): Every plan change on the subscription, newest first. - `id` (string): The plan change. - `direction` (string): `upgrade` or `downgrade`. - `status` (string): `awaiting_payment` (an upgrade not paid yet), `scheduled` (a downgrade, or an upgrade at the next renewal, waiting for the period end), `applied`, `lapsed` (an upgrade not paid in time), `undone` (a scheduled change taken back), `replaced` (another change took its place) or `canceled` (the subscription ended first). - `from_price` (object): The price before, in the same shape as above. - `to_price` (object): The new price. - `requested_by` (string): `customer` or `merchant`. - `amount` (integer, nullable): What the upgrade charges. Null for a downgrade. - `credit` (integer, nullable): The unused time taken off the upgrade. Null for a downgrade. - `effective_at` (timestamp, nullable): When it took effect, or for a downgrade, when it will. Null for an upgrade that hasn't taken effect. - `created_at` (timestamp): When it was requested. - `resolved_at` (timestamp, nullable): When it left the pending state. If the app has no subscription with that ID, returns `404` with code `not_found`. **GET /v1/apps/{appID}/subscriptions/{id}** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", { headers: { Authorization: "Bearer sk_test_..." }, }); const subscription = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", headers={"Authorization": "Bearer sk_test_..."}, ) subscription = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $subscription = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", 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 subscription map[string]any json.NewDecoder(res.Body).Decode(&subscription) ``` **Response** ```json { "subscription": { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null }, "subscription_page_url": "https://app.abuna.app/portal/8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "customer": { "id": "Cu5tM8rA", "app_id": "8ddhXCDW", "name": "Jane Doe", "phone_number": "+237671234567", "email": "jane@example.com", "created_at": 1727600000, "metadata": {}, "language": null, "updates": { "channel": null, "email": { "status": "active" }, "telegram": { "status": "off", "connected_at": null, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } }, "telegram_connected": false }, "price": { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "created_at": 1727600000, "archived_at": null }, "periods": [ { "id": "T6yVr3Dp", "starts_at": 1727600000, "ends_at": 1730192000, "grace_period_ends_at": 1727686400, "paid_at": 1727600100, "pay_url": "https://app.abuna.app/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "invoice": { "id": "V2nC8xEi", "app_id": "8ddhXCDW", "period_id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "number": "MYST-000124", "status": "paid", "kind": "period", "amount": 5000, "credit": 0, "currency": "XAF", "item_label": "Monthly", "buyer_name": "Jane Doe", "buyer_email": "jane@example.com", "seller_name": "My store", "period_start": 1727600000, "period_end": 1730192000, "due_at": 1727686400, "created_at": 1727600000, "paid_at": 1727600100, "voided_at": null, "discount": 0, "coupon_id": null, "promotion_code_id": null }, "invoice_url": "https://app.abuna.app/invoice/V2nC8xEi?exp=1728204800&sig=b4e1c8f2a7d3960e5b1f8c4a2d7e3b9f6a0c5e8d1b4f7a2c9e6d3b0f8a5c1e7d" } ], "payments": [ { "id": "m7Yw4NcJ", "app_id": "8ddhXCDW", "period_id": "T6yVr3Dp", "driver": "sandbox", "provider": "test", "provider_reference": "test_9f3b7d1a5c2e8f4b6d0a", "amount": 5000, "currency": "XAF", "status": "succeeded", "message": null, "created_at": 1727600090, "fee": 100, "net": null, "session_id": null, "note": null, "marked_by_user_id": null, "marked_by_api_key_id": null, "method_label": "Successful payment (test)" } ], "pending_change": { "id": "H3nM8cGb", "type": "downgrade", "price": { "id": "Kw3FgT7e", "name": "Basic monthly", "amount": 2000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "requested_by": "customer", "created_at": 1728464000, "amount_due": null, "credit": null, "expires_at": null, "pay_url": null, "effective_at": 1730192000 }, "plan_offer": null, "plan_changes": [ { "id": "H3nM8cGb", "direction": "downgrade", "status": "scheduled", "from_price": { "id": "Zt6YbN3q", "name": "Monthly", "amount": 5000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "to_price": { "id": "Kw3FgT7e", "name": "Basic monthly", "amount": 2000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "requested_by": "customer", "amount": null, "credit": null, "effective_at": 1730192000, "created_at": 1728464000, "resolved_at": null } ] } ``` ## Update a subscription `PATCH /v1/apps/{appID}/subscriptions/{id}` Sets the subscription's `metadata`. The map you send replaces the whole map: keys you leave out are removed. Send `{}` to clear it. **Parameters** - `metadata` (object, required): The new metadata. See [Metadata](https://abuna.app/docs/api/subscriptions.md#metadata) for the limits. Returns the subscription. Metadata past its limits returns `422` with code `invalid` and an `errors` item for `metadata`. If the app has no subscription with that ID, returns `404` with code `not_found`. **PATCH /v1/apps/{appID}/subscriptions/{id}** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \ -X PATCH \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"metadata": {"user_id": "42"}}' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", { method: "PATCH", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ metadata: { user_id: "42" } }), }); const subscription = await response.json(); ``` **Response** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## Cancel a subscription `POST /v1/apps/{appID}/subscriptions/{id}/cancel` Ends the subscription, now or at the end of the paid period. Send `at_period_end` to choose. An empty body, or `false`, cancels now. To have the customer confirm the cancel themselves, use [Create a cancel session](https://abuna.app/docs/api/sessions.md#create-cancel). During a trial, `at_period_end: true` sets `cancel_at` to `trial_ends_at`. The subscription stays `trialing` until then, with access and no invoice to pay. An immediate API cancel still ends it now. **Body parameters** - `at_period_end` (boolean): Optional, `false` by default. With `true`, the subscription stays `active` until the current paid period ends, and then ends by itself. A value that isn't a boolean returns `400` with code `invalid_json`. **Now.** The subscription is `canceled` at once, with `canceled_at` set and `cancel_at` null. Abuna voids its open invoices, sends a `subscription.canceled` event with reason `merchant`, and tells the customer. Canceling now on a subscription with a scheduled cancel ends it now and clears the schedule. It also voids an upgrade waiting for payment and withdraws a pending plan change offer. **At the end of the paid period.** The response has `status` `active` and `cancel_at` set to the end of the paid period. Abuna sends a `subscription.updated` event and tells the customer when it ends and how to keep it. Until then it issues no renewal and sends no renewal reminders, and `next_payment_at` in the list is null. When the date arrives, the subscription becomes `canceled` and Abuna sends `subscription.canceled`. Sending `at_period_end` again while a cancel is scheduled returns `200` and changes nothing: no new event and no new email. A scheduled cancel replaces a scheduled downgrade or an upgrade waiting for payment. See [One change at a time](https://abuna.app/docs/api/subscriptions.md#one-change-at-a-time). Outside a trial, if the current period isn't paid yet, or has already ended, `at_period_end: true` cancels now instead. Check `status` in the response to see which happened. A renewal invoice sent before the end and not paid yet is voided, so the customer can't pay for a period after the end. If they already paid it, the subscription ends when that renewal ends. > **Warning:** A canceled subscription can't be restarted. To bill the customer again, create a new subscription. Returns the subscription. If the app has no subscription with that ID, or it is already canceled, returns `404` with code `not_found`. If `at_period_end` would replace an upgrade whose payment is in progress, returns `409` with code `payment_in_progress`. **POST /v1/apps/{appID}/subscriptions/{id}/cancel** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel \ -X POST \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"at_period_end": true}' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ at_period_end: true }), }); const subscription = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel", headers={"Authorization": "Bearer sk_test_..."}, json={"at_period_end": True}, ) subscription = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["at_period_end" => true]), CURLOPT_RETURNTRANSFER => true, ]); $subscription = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel", strings.NewReader(`{"at_period_end": true}`)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var subscription map[string]any json.NewDecoder(res.Body).Decode(&subscription) ``` **Response** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": 1730192000, "cancel_at_period_end": true, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## Keep a subscription `POST /v1/apps/{appID}/subscriptions/{id}/resume` Undoes a scheduled cancel. Billing carries on as before: `cancel_at` is null again and the next renewal is issued on time. Abuna sends a `subscription.updated` event and tells the customer the subscription continues. It also undoes a [scheduled downgrade](https://abuna.app/docs/api/subscriptions.md#downgrades), or an [upgrade at the next renewal](https://abuna.app/docs/api/subscriptions.md#upgrades), so the next period stays at the current price. Abuna sends `subscription.updated` with a `downgrade_undone` or `upgrade_undone` change, and no email. If nothing is scheduled on an active subscription, returns `200` and changes nothing. If the subscription is already canceled, returns `409` with code `subscription_canceled`. If the app has no subscription with that ID, returns `404` with code `not_found`. **POST /v1/apps/{appID}/subscriptions/{id}/resume** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume \ -X POST \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const subscription = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume", headers={"Authorization": "Bearer sk_test_..."}, ) subscription = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $subscription = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume", 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 subscription map[string]any json.NewDecoder(res.Body).Decode(&subscription) ``` **Response** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## List plan options `GET /v1/apps/{appID}/subscriptions/{id}/plan-options` Lists the prices the subscription can move to, each quoted as of now. Amounts change as the period runs down, so quote again right before you show them. See [Changing plan](https://abuna.app/docs/api/subscriptions.md#changing-plan) for how each number is worked out. **Each option** - `price` (object): The price: `id`, `name`, `amount`, `currency`, `interval` and `interval_count`. - `direction` (string): `upgrade` or `downgrade`. - `amount_due` (integer): For an upgrade, what the customer pays now. It can be `0`. Always `0` for a downgrade. - `credit` (integer): For an upgrade, the unused time of the current period taken off the new price. Always `0` for a downgrade. - `new_billing_date` (timestamp, nullable): For an upgrade, when the new period would end if paid now. Null for a downgrade. - `effective_at` (timestamp, nullable): For a downgrade, when the new price starts: the end of the paid period. Null for an upgrade. Returns `{ "data": [...] }`. The list is empty when no other price is eligible or the subscription isn't `active` or `past_due`. If the app has no subscription with that ID, returns `404` with code `not_found`. **GET /v1/apps/{appID}/subscriptions/{id}/plan-options** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options", { headers: { Authorization: "Bearer sk_test_..." }, }); const options = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options", headers={"Authorization": "Bearer sk_test_..."}, ) options = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $options = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options", 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 options map[string]any json.NewDecoder(res.Body).Decode(&options) ``` **Response** ```json { "data": [ { "price": { "id": "Hc8LmV2s", "name": "Pro monthly", "amount": 10000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "direction": "upgrade", "amount_due": 6666, "credit": 3334, "new_billing_date": 1731142400, "effective_at": null }, { "price": { "id": "Kw3FgT7e", "name": "Basic monthly", "amount": 2000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "direction": "downgrade", "amount_due": 0, "credit": 0, "new_billing_date": null, "effective_at": 1730192000 } ] } ``` ## Statuses - **`trialing`**: free access until `trial_ends_at`. Keep access during the trial. Customers in Live count toward your team's subscriber limit; Test has no subscriber limit. - **`pending`**: created, and waiting for the first payment. If the first period isn't paid by its pay-by date, the subscription is `canceled` with `ended_reason` `unpaid`. - **`active`**: every period that has started is paid. - **`past_due`**: unpaid. A renewal has started and isn't paid yet. - **`canceled`**: ended. `ended_reason` says why. A canceled subscription can't be restarted. ### Renewals and unpaid subscriptions Abuna issues the next billing period and its invoice before the paid period ends. Your app's [`renewal_lead_days`](https://abuna.app/docs/api/apps.md#object) sets how many days ahead: 0 to 7, 3 by default, and never earlier than half the period. Abuna sends `subscription.renewed` and `invoice.created`, and emails the customer the invoice with its pay link. The subscription stays `active`, and the customer can pay right away. The new period always starts when the paid one ends, even if the customer pays early. If the renewal is still unpaid when the paid period ends, the subscription becomes `past_due` and Abuna sends `subscription.past_due`. When the invoice is paid, the subscription is `active` again, and Abuna sends `subscription.recovered`. A renewal paid before the paid period ends never goes through `past_due`. With `renewal_lead_days` at `0`, or while a downgrade waits for the period's end, the invoice goes out as the period ends, so the subscription is `past_due` until the customer pays. If the period isn't paid by its pay-by date, the subscription is `canceled` with `ended_reason` `unpaid`, and Abuna sends `subscription.canceled` with reason `non_payment`. The pay-by date is the billing period's `grace_period_ends_at`: the period's start plus your app's days to pay, [`grace_period_days`](https://abuna.app/docs/api/apps.md#object) (1 to 14, 3 by default), and never later than the period's end. > **Note:** Keep the customer's access while the subscription is `past_due`, and stop it when the subscription is `canceled`. An unpaid customer still has days to pay. Cutting access early locks out customers who are about to pay. `current_period_start` and `current_period_end` keep showing the last paid period while the subscription is `past_due`. A `past_due` subscription can still: - Be paid through its pay link, a [payment session](https://abuna.app/docs/api/sessions.md#create-payment) or the customer portal. - Be [canceled](https://abuna.app/docs/api/subscriptions.md#cancel). A cancel at the end of the paid period ends it now, because the current period isn't paid. - [Changing plan](https://abuna.app/docs/api/subscriptions.md#changing-plan). An upgrade starts a full period at the new price now, and a downgrade waits for the current period's end. See [Upgrades](https://abuna.app/docs/api/subscriptions.md#upgrades). ### Payments that arrive late A mobile money payment the customer approved can be confirmed hours later. If the invoice was voided in the meantime, Abuna still records the payment: it is `succeeded`, the invoice becomes `paid`, Abuna sends `invoice.paid`, and the customer gets a receipt. - If the subscription ended only because this payment hadn't arrived (`ended_reason` `unpaid`), and the period it pays for hasn't ended yet, the subscription comes back: `status` is `active`, `canceled_at` and `ended_reason` are null again, and Abuna sends `subscription.recovered`, or `subscription.paid` for a first payment. A first payment needs room in the Live subscriber limit of your team's plan, as at checkout. - Otherwise the subscription stays as it is: canceled by you or the customer, replaced, past the paid period, or an upgrade that expired. You may want to refund the customer. Either way, team members who get emails about payments or cancellations get one about it. ## Metadata `metadata` holds your own keys and values on a subscription, for example your user ID. Set it when you [create the subscription](https://abuna.app/docs/api/subscriptions.md#create), pass it to a [checkout session](https://abuna.app/docs/api/sessions.md#create-checkout), or [update it](https://abuna.app/docs/api/subscriptions.md#update) later. Every read returns it. - Up to 20 keys. - Each key is 1 to 40 characters. - Each value is a string of up to 500 characters. Numbers, booleans, objects and null aren't allowed. The `subscription`, `invoice` and `plan_offer` events carry this subscription's metadata. Session events carry the session's own metadata instead. Pass metadata on every session you create. See [Event types](https://abuna.app/docs/api/events.md#types). ## Canceling a subscription During a free trial, a customer's cancel is scheduled for `trial_ends_at`, with access until then. Any unpaid first invoice is canceled, so nothing remains to pay. The API can still [cancel immediately](https://abuna.app/docs/api/subscriptions.md#cancel). A cancel can take effect now or at the end of the paid period. You choose when you cancel from the dashboard or the API. For customers who cancel in the customer portal, the app's **When customers cancel** setting decides, which is [`customer_cancel`](https://abuna.app/docs/api/apps.md#object). New apps start with `at_period_end`. A [cancel session](https://abuna.app/docs/api/sessions.md#create-cancel) uses that setting too, unless you send `at_period_end`. - **Now.** The subscription ends at once and any unpaid invoice is voided. - **End of the paid period.** The subscription stays `active` and carries `cancel_at`. The customer keeps access they paid for. Abuna issues no renewal and sends no renewal reminders, and voids a renewal invoice it already sent and that isn't paid. A renewal the customer already paid counts as paid period, so the subscription ends when it ends. The dashboard and the customer portal show "Ends on" with the date. At that moment the subscription becomes `canceled`. - **Unpaid period.** If the current period isn't paid yet, an end-of-period cancel ends the subscription now and voids the unpaid invoice. The dashboard and the customer portal say so before the person confirms. - **Undo.** Until the end date, you can keep the subscription in the dashboard or with [the resume endpoint](https://abuna.app/docs/api/subscriptions.md#resume), and the customer can keep it in the portal. Billing carries on as before. The customer gets one email when a cancel is scheduled, with the end date and how to keep the subscription, one when it ends, and one short confirmation if it is undone. Your webhook URL gets `subscription.updated` when a cancel is scheduled or undone, and `subscription.canceled` when the subscription ends. See [Customer notifications](https://abuna.app/docs/guides/customer-notifications.md). Test mode works the same way. Abuna records the emails for a Test customer instead of sending them, and Test and Live apps keep their own **When customers cancel** setting. ## Changing plan An `active` or `past_due` subscription can move to another price. The customer does it in the customer portal, or confirms a change you send them to with a [plan change session](https://abuna.app/docs/api/sessions.md#create-plan-change). A customer who comes back to a checkout for another price of the same product is offered the change there too: see [Switching plan at checkout](https://abuna.app/docs/api/sessions.md#checkout-switch). You can't change the price directly, because an upgrade needs the customer to pay. ### Which prices Any other price of the same product in the same currency, unless it is archived. Never a price of another product or in another currency: a change to a price in another currency returns `422` with code `price_not_eligible`. If no price is eligible, the portal shows no option to change plan. A subscription that is still `pending` can't change plan. ### Upgrade or downgrade Abuna compares cost per day: the price's amount divided by the length in days of one of its periods starting now. A price that costs more per day is an upgrade. One that costs the same or less is a downgrade. This works across intervals, so moving from monthly to yearly follows the same rule. ### Upgrades If the current period is paid, the customer pays the difference now and keeps the old plan until that payment succeeds. A renewal invoice already sent for the old price and not paid is voided, and the next one is issued at the new price. If the customer already paid the next period before it started, an upgrade waits until that period starts: until then the portal offers no upgrade, and a change returns `409` with code `renewal_paid_early`. At that moment the new plan starts with a fresh full period at the new price, and the billing date moves to the payment date. The amount is the new price minus the unused value of the current period. The unused value is the period's value times the whole days left, divided by the days in the period. The period's value is what its invoice charged plus any credit on it, so a second upgrade in the same period loses nothing. The result is rounded down and never goes below `0`. With 20 of 30 days left on a FCFA 5,000 period, moving to a FCFA 10,000 price costs `10000 − 3334 = 6666`, and `credit` is `3334`. An amount above `0` but under the minimum charge, FCFA 100 or 50 US cents, is raised to it, and `credit` is lower by the same amount. With a discount that covers the new price, the new price is the discounted one. - **Nothing to pay.** When the amount is `0`, the upgrade takes effect at once. Its invoice is created already paid. - **Not paid in time.** The upgrade lapses at its `expires_at`: your app's days to pay from the request, or the end of the current period if that comes first. Its invoice is voided and the old plan carries on. There is no penalty. If the upgrade replaced a scheduled cancel, the cancel is scheduled again for its original date, and `subscription.updated` carries its `cancel_at`. - **Unpaid current period.** If the current period isn't paid yet, as while the subscription is `past_due`, Abuna voids its invoice and starts a full period at the new price now. The new plan is in force at once and the customer pays it through its pay link, with the usual days to pay. There is no credit. While a payment on the old invoice is in progress, the change returns `409` with code `payment_in_progress`. A switch at a checkout session created with `upgrade_timing` `next_renewal` is the exception: the upgrade costs nothing now and is scheduled for the end of the paid period, like a downgrade. It shows in `pending_change` and `scheduled_price_change`, sends `subscription.updated` with an `upgrade_scheduled` change, and can be undone the same way. An upgrade's invoice has `kind` `plan_change` and the unused time in `credit`. Its `amount` is what the customer pays. An upgrade with something to pay needs your app to take payments. Until it can, the change returns `422` with code `not_accepting_payments`. An upgrade with nothing to pay, and a downgrade, work either way. ### Downgrades A downgrade costs nothing now and refunds nothing. The customer keeps the current plan until the paid period ends, and the next period is issued at the new price when the paid period ends, not before. A renewal invoice already sent for the old price and not paid is voided. If the customer already paid the next period, the downgrade starts when that period ends. Until then, the customer can undo it in the customer portal, and you can with [Keep a subscription](https://abuna.app/docs/api/subscriptions.md#resume). A scheduled downgrade shows in `pending_change` and in `scheduled_price_change` on [`subscription.updated`](https://abuna.app/docs/api/events.md#subscription-updated). A downgrade can be scheduled while the current period is still unpaid. It still starts at that period's end, and if the period stays unpaid, the subscription ends for non-payment as usual. While a downgrade is scheduled, the renewal reminder quotes the new price. ### One change at a time A subscription holds at most one of these: a scheduled cancel, a scheduled downgrade or upgrade, or an upgrade waiting for payment. Starting one replaces the other. A replaced upgrade has its invoice voided, and the replaced change gets status `replaced`. While that upgrade's payment is in progress, it can't be replaced: the request returns `409` with code `payment_in_progress`. Asking again for the change already waiting, to the same price, changes nothing and returns it as it stands. A change you send the customer with a [plan change session](https://abuna.app/docs/api/sessions.md#create-plan-change) waits for them to confirm it. A subscription has at most one change waiting to be confirmed. A new one, or a plan change the customer makes in the portal, replaces it. Confirming it replaces a scheduled cancel, a scheduled downgrade or an upgrade waiting for payment, and the confirm page says so first. Canceling the subscription now voids an upgrade waiting for payment and withdraws the change waiting to be confirmed. ### In the customer portal The customer portal lists each eligible price with what it costs now: the amount to pay and the new billing date for an upgrade, or the date it starts for a downgrade. An upgrade sends the customer to its pay link, unless there is nothing to pay. While an upgrade waits for payment, the portal shows it with its pay link. Keeping the subscription in the portal also undoes a scheduled downgrade. To send a customer to the portal with a link back to your app, use [Create a portal session](https://abuna.app/docs/api/sessions.md#create-portal). ### The confirm page The `url` of a [plan change session](https://abuna.app/docs/api/sessions.md#create-plan-change) opens a page with the current plan, the new one and what the change costs, worked out when the page loads. The customer confirms there, and the change follows the same rules as in the portal. The page stops working when the session expires (7 days, or the end of the current period if that comes first), when a newer change replaces it, or once it is used. Abuna doesn't email the customer when you create a plan change session, so send them to its `url` yourself. The customer gets an email when an upgrade takes effect and when a downgrade is scheduled. Nothing is sent when an upgrade starts waiting for payment, when it lapses, or when a downgrade is undone. See [Customer notifications](https://abuna.app/docs/guides/customer-notifications.md). In Test mode, Abuna records these emails instead of sending them.