Skip to content
ABUNA
DocsSubscriptions

API reference

Subscriptions

Start, list, read, update, cancel, keep and change the plan of a customer's subscription.

View as Markdown

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.

The subscription object

Attributes

  • idstring

    Unique identifier for the subscription.
  • app_idstring

    The app the subscription belongs to.
  • customer_idstring

    The customer who pays.
  • price_idstring

    The price the customer pays.
  • statusstring

    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.
  • starts_attimestamp

    When the subscription starts, including its free trial if any, in Unix seconds.
  • activated_attimestampnullable

    When the trial started, or the first period was paid without a trial.
  • trial_ends_attimestampnullable

    When the free trial ends, in Unix seconds. Null for a subscription without a trial.
  • canceled_attimestampnullable

    When the subscription was canceled.
  • cancel_attimestampnullable

    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_endboolean

    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_starttimestampnullable

    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_endtimestampnullable

    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_reasonstringnullable

    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.
  • metadataobject

    Your own keys and values. {} when there are none. A subscription started by a checkout session gets the session's. See Metadata.
  • created_attimestamp

    When the subscription was created, in Unix seconds.
  • manage_tokenstring

    The token in the customer portal link. Anyone with the link can see and cancel the subscription, so keep it private.
  • discountobjectnullable

    The coupon the subscription holds. Null without one. See Run a sale with promotion codes.
    Show child attributesHide child attributes
    • couponobject

      The coupon.
    • promotion_codestringnullable

      The ID of the promotion code that brought the coupon. Null when you applied the coupon directly, without a code.
    • starttimestamp

      When the discount started, in Unix seconds.
    • endtimestampnullable

      For repeating, when the discount stops. Null for once and forever.
The subscription object
{
  "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

Accepts an Idempotency-Key header.

Without a trial, starts a pending subscription and its first billing period, 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.

With an eligible trial, starts trialing instead, without an immediate charge. The first paid period starts at trial_ends_at. See Free trials for billing, eligibility and webhooks.

Parameters

  • customer_idstringrequired

    The customer to bill.
  • price_idstringrequired

    The price to bill them.
  • trial_daysinteger

    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.
  • discountsarray

    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.
  • metadataobject

    Your own keys and values. See 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 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"}'
Response
{
  "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

  • statusstring

    Returns only subscriptions with this status: pending, trialing, active, past_due or canceled.
  • customer_idstring

    Returns only this customer's subscriptions.
  • emailstring

    Returns only subscriptions whose customer's email contains this text. Case doesn't matter.
  • limitinteger

    How many subscriptions to return, from 1 to 100. Defaults to 50.
  • cursorstring

    The next_cursor from the previous page. Send the same filters with it.

Extra attributes

  • customerobject

    Who pays.
    Show child attributesHide child attributes
    • namestringnullable

      The customer's name.
    • emailstring

      The customer's email address.
  • priceobject

    What they pay.
    Show child attributesHide child attributes
    • namestring

      The price's name.
    • amountinteger

      The amount for each period, in the currency's smallest unit.
    • currencystring

      XAF, XOF or USD.
    • intervalstring

      day, week, month or year.
    • interval_countinteger

      How many intervals make up one period.
  • next_payment_attimestampnullable

    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. An unknown status or a limit outside 1 to 100 returns 422 with code invalid.

GET /v1/apps/{appID}/subscriptions
curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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

  • subscriptionobject

    The subscription object.
  • subscription_page_urlstring

    The customer portal link, where the customer sees and cancels the subscription.
  • customerobject

    The customer object, plus telegram_connected.
  • priceobject

  • periodsarray

    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.
    Show child attributesHide child attributes
    • idstring

      The billing period's ID.
    • starts_attimestamp

      When the period starts.
    • ends_attimestamp

      When the period ends.
    • grace_period_ends_attimestamp

      The pay-by date.
    • paid_attimestampnullable

      When the period was paid.
    • pay_urlstring

      The pay link for the period.
    • invoiceobjectnullable

      The period's invoice object.
    • invoice_urlstringnullable

      A link to the invoice page. It expires after 7 days.
  • paymentsarray

    Every payment on the subscription, newest first.
  • pending_changeobjectnullable

    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.
    Show child attributesHide child attributes
    • idstring

      The plan change.
    • typestring

      upgrade or downgrade.
    • priceobject

      The new price: id, name, amount, currency, interval and interval_count.
    • requested_bystring

      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_attimestamp

      When the change was requested.
    • amount_dueintegernullable

      What the customer pays to switch now. Null for a downgrade, and 0 for an upgrade at the next renewal.
    • creditintegernullable

      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_attimestampnullable

      If the upgrade isn't paid by then, it lapses and the current plan carries on. Null for a scheduled change.
    • pay_urlstringnullable

      The pay link for the upgrade. Null for a scheduled change.
    • effective_attimestampnullable

      When a scheduled change starts. Null for an upgrade waiting for payment.
  • plan_offerobjectnullable

    The plan change waiting for the customer to confirm, or null. It is null once it is past its expires_at.
    Show child attributesHide child attributes
    • idstring

      The offer.
    • priceobject

      The price offered: id, name, amount, currency, interval and interval_count.
    • statusstring

      Always pending here.
    • urlstring

      The page where the customer confirms the change.
    • created_attimestamp

      When the offer was made.
    • expires_attimestamp

      When the offer runs out if the customer hasn't confirmed it.
    • sent_attimestampnullable

      When Abuna sent the customer the link, or null when it didn't send one.
  • plan_changesarray

    Every plan change on the subscription, newest first.
    Show child attributesHide child attributes
    • idstring

      The plan change.
    • directionstring

      upgrade or downgrade.
    • statusstring

      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_priceobject

      The price before, in the same shape as above.
    • to_priceobject

      The new price.
    • requested_bystring

      customer or merchant.
    • amountintegernullable

      What the upgrade charges. Null for a downgrade.
    • creditintegernullable

      The unused time taken off the upgrade. Null for a downgrade.
    • effective_attimestampnullable

      When it took effect, or for a downgrade, when it will. Null for an upgrade that hasn't taken effect.
    • created_attimestamp

      When it was requested.
    • resolved_attimestampnullable

      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 https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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

  • metadataobjectrequired

    The new metadata. See 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 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"}}'
Response
{
  "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

Accepts an Idempotency-Key header.

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.

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_endboolean

    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.

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.

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 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}'
Response
{
  "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

Accepts an Idempotency-Key header.

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, or an upgrade at the next renewal, 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 https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume \
  -X POST \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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 for how each number is worked out.

Each option

  • priceobject

    The price: id, name, amount, currency, interval and interval_count.
  • directionstring

    upgrade or downgrade.
  • amount_dueinteger

    For an upgrade, what the customer pays now. It can be 0. Always 0 for a downgrade.
  • creditinteger

    For an upgrade, the unused time of the current period taken off the new price. Always 0 for a downgrade.
  • new_billing_datetimestampnullable

    For an upgrade, when the new period would end if paid now. Null for a downgrade.
  • effective_attimestampnullable

    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 https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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 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 (1 to 14, 3 by default), and never later than the period's end.

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 or the customer portal.
  • Be canceled. A cancel at the end of the paid period ends it now, because the current period isn't paid.
  • 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.

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, pass it to a checkout session, or update it 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.

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.

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. New apps start with at_period_end. A cancel session 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, 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.

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. 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. 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. A scheduled downgrade shows in pending_change and in scheduled_price_change on 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 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.

The url of a plan change session 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. In Test mode, Abuna records these emails instead of sending them.

Next steps