Skip to content
ABUNA
DocsApps

API reference

Apps

Read the app a key belongs to: its mode, keys, and checkout settings.

View as Markdown

Retrieve the app your secret key belongs to, with its billing settings and how ready it is to take payments. An app holds your products, prices, customers and subscriptions, and has a Live mode and a Test mode.

The API gives each mode its own app ID and its own keys, so this page says Live app and Test app for them. A secret key works only for its own mode.

The app object

Attributes

  • idstring

    Unique identifier for the app.
  • team_idstring

    The team that owns the app.
  • namestring

    The app's name. Its Live and Test apps share it.
  • slugstring

    A URL-safe form of the name. A Test app's slug ends in -test.
  • environmentstring

    live or test.
  • project_idstring

    The ID of the Live app. For a Live app, this is its own ID.
  • live_app_idstring

    The ID of the Live app. Always the same as project_id.
  • test_app_idstring

    The ID of the Test app. For a Test app, this is its own ID. Left out when the app has no Test mode.
  • base_currencystring

    The app's currency: XAF, XOF or USD.
  • grace_period_daysinteger

    The days to pay: how many days you give customers to pay a renewal, from 1 to 14. They count from the start of the period and never run past its end. If the renewal is still unpaid after them, Abuna cancels the subscription and tells the customer. New apps start at 3.
  • renewal_lead_daysinteger

    How many days before a paid period ends the renewal invoice goes out, from 0 to 7, so the customer can pay in advance. The new period still starts on the renewal date, even when the customer pays early. With 0, the invoice goes out on the renewal date. It never goes out before the middle of the paid period, so on a daily price it goes out 12 hours before the end. New apps start at 3. Change it in the dashboard under Settings, Renewals and days to pay. See Renewals and unpaid subscriptions.
  • invoice_prefixstring

    What comes before the count in the app's invoice numbers, like MYST in MYST-000124: 2 to 10 capital letters (A to Z) or digits. New apps start with the first 4 letters and digits of the app's name, or INV when the name has fewer than 2. A change applies to invoices issued afterwards. Numbers already issued stay as they are. Live and Test apps each have their own value. Change it in the dashboard under Settings, Invoice numbers.
  • customer_cancelstring

    What happens when a customer cancels in the customer portal. at_period_end (the default) keeps the subscription until the paid period ends. immediate ends it now. An unpaid period always ends now. Live and Test apps each have their own value. Change it in the dashboard under Settings, When customers cancel.
  • publishable_keystring

    The key for checkout links, like pk_test_ followed by 48 hex characters.
  • secret_key_prefixstring

    The start of the app's first secret key: its prefix and the next 8 characters.
  • webhook_urlstringnullable

    Where Abuna sends webhooks.
  • webhook_eventsarray

    The event types sent to webhook_url. It can list events while webhook_url is null, but nothing is sent until a URL is set. Removing the URL keeps the list. An app created before 10 October 2026 lists every event type that existed on that date, until you change its events. Change them in the dashboard under Webhooks. See Choose your events.
  • webhook_configuredboolean

    true when webhook_url is set.
  • webhook_testedboolean

    true once a Send test event from the dashboard has reached the current webhook_url. Changing the URL sets it back to false.
  • success_urlstringnullable

    Where the checkout page sends the customer after they pay. A checkout session can set its own.
  • cancel_urlstringnullable

    Where the checkout page sends the customer when they leave without paying. A checkout session can set its own.
  • support_emailstringnullable

    The support email your customers see. The Live and Test apps share it. A Live app needs this or support_url to take payments.
  • support_urlstringnullable

    The support page your customers see. The Live and Test apps share it. A Live app needs this or support_email to take payments.
  • terms_urlstringnullable

    The terms page your customers see.
  • timezonestring

    The IANA time zone, like Africa/Douala, for the dates and times in every email about the app. New apps start with Africa/Douala. A scheduled price change starts at midnight in this zone. The Live and Test apps share it. Change it in the dashboard under Settings, General, Time zone.
  • brandingobject

    How your customer pages look. The Live and Test apps share it.
    Show child attributesHide child attributes
    • accent_colorstringnullable

      The color of the main button, links, and selected choices on your checkout and pay pages, customer portal and invoices, like #1F6FEB. Where it's hard to read on the page, links and focus outlines use a darker or lighter shade of it. The button's text is white or black, whichever reads better. null keeps Abuna's colors. Change it in the dashboard under Settings, General, Branding.
  • telegram_updatesboolean

    Whether customers can choose Telegram for their messages, at checkout once they pay and in the customer portal. When false, checkout doesn't offer it and Telegram messages stop for every customer. They still get email. New apps start with true. Live and Test apps each have their own value. Change it in the dashboard under Settings, General, Customer messages. See Customer messages.
  • whatsapp_updatesboolean

    Whether customers can choose WhatsApp for their messages, at checkout once they pay and in the customer portal. When false, checkout doesn't offer it and WhatsApp messages stop for every customer. They still get email. New apps start with false. A Live app needs your team on the Plus plan or higher. In Test mode it works on any plan. Live and Test apps each have their own value. Change it in the dashboard under Settings, General, Customer messages. See Customer messages.
  • daily_remindersboolean

    Whether customers get a reminder each day after the renewal date until they pay, and a last reminder the day before their subscription is canceled. When false, they hear about a renewal only when its invoice goes out and when the subscription is canceled for not paying. New apps start with false. A Live app needs your team on the Plus plan or higher; on Free it sends only those two messages, even when this is true. In Test mode it works on any plan. Live and Test apps each have their own value. Change it in the dashboard under Settings, General, Customer messages. See Daily reminders.
  • paymentsobject

    Whether the app can take payments, and what it still needs if not.
    Show child attributesHide child attributes
    • readyboolean

      true when email_verified, provider_connected, and support_contact are all true.
    • email_verifiedboolean

      Whether the team owner has verified their email. Always true in Test mode.
    • provider_connectedboolean

      Whether a payment provider is connected. Always true in Test mode.
    • support_contactboolean

      Whether the app has a support_email or support_url. Always true in Test mode.
    • providers_availableboolean

      Whether there is at least one payment provider you can connect in this app's mode.
    • webhook_confirmedboolean

      Whether a team owner confirmed in the dashboard that the webhook URL is set at the payment provider. Always true in Test mode.
    • webhook_receivedboolean

      Whether your payment provider's webhook has reached Abuna at least once. Always true in Test mode.
    • provider_namestringnullable

      The connected payment provider's name, or Abuna with abuna_payments.enabled. null when none is connected, and always in Test mode.
    • account_idstringnullable

      The ID of the payment account the app uses. null whenever provider_name is, and with abuna_payments.enabled.
    • account_namestringnullable

      That account's name, as shown on your team's Payment accounts page. null whenever provider_name is, and with abuna_payments.enabled.
    • abuna_paymentsobject

      Abuna payments for this app: whether you can turn it on, and whether it's on.
      Show child attributesHide child attributes
      • availableboolean

        Whether this app can turn on Abuna payments. Always false in Test mode.
      • enabledboolean

        Whether Abuna payments is on for this app. When true, provider_connected, webhook_confirmed, and webhook_received are true. A team owner turns it on in the dashboard under Settings, Payments.
  • liveobject

    How close a Live app is to taking real payments. Left out for a Test app.
    Show child attributesHide child attributes
    • readyboolean

      true once payments.ready is true and payments.webhook_confirmed or payments.webhook_received is true. It doesn't need a first payment.
    • steps_doneinteger

      How many of the steps to go Live are done: the team owner verifies their email, you connect a payment provider, you add a support contact, and you set the webhook URL at the provider.
    • steps_totalinteger

      How many steps there are to go Live: 4.
  • read_onlyboolean

    true when this Live app is over your team's plan limits and is read-only. Writes then fail with 403. Always false in Test mode.
  • whatsapp_availabilityobject

    Whether whatsapp_updates can be turned on.
    Show child attributesHide child attributes
    • availableboolean

      true when the app can offer WhatsApp messages.
    • reasonstringnullable

      Why it can't, or null when it can: whatsapp_unavailable when Abuna can't send WhatsApp messages right now, or whatsapp_plan_required when a Live app needs the Plus plan or higher.
  • daily_reminders_availableboolean

    Whether your team's plan lets this app send daily_reminders. Always true in Test mode.
  • bills_plansboolean

    Always false for your apps. You can ignore it.
  • created_attimestamp

    When the app was created, in Unix seconds.
The app object
{
  "id": "8ddhXCDW",
  "team_id": "01J9ZQ3A1B2C3D4E5F6G7H8J9K",
  "name": "My store",
  "slug": "my-store-test",
  "environment": "test",
  "project_id": "Q7mKp2Rt",
  "live_app_id": "Q7mKp2Rt",
  "test_app_id": "8ddhXCDW",
  "base_currency": "XAF",
  "grace_period_days": 3,
  "renewal_lead_days": 3,
  "invoice_prefix": "MYST",
  "customer_cancel": "at_period_end",
  "publishable_key": "pk_test_...",
  "secret_key_prefix": "sk_test_3f9c1a2b",
  "webhook_url": "https://example.com/webhooks",
  "webhook_events": ["session.completed", "subscription.paid", "subscription.canceled", "invoice.paid"],
  "webhook_configured": true,
  "webhook_tested": true,
  "success_url": null,
  "cancel_url": null,
  "support_email": "support@example.com",
  "support_url": null,
  "terms_url": null,
  "timezone": "Africa/Douala",
  "branding": {
    "accent_color": "#1F6FEB"
  },
  "telegram_updates": true,
  "whatsapp_updates": false,
  "daily_reminders": false,
  "payments": {
    "ready": true,
    "email_verified": true,
    "provider_connected": true,
    "support_contact": true,
    "providers_available": true,
    "webhook_confirmed": true,
    "webhook_received": true,
    "provider_name": null,
    "account_id": null,
    "account_name": null,
    "abuna_payments": {
      "available": false,
      "enabled": false
    }
  },
  "read_only": false,
  "whatsapp_availability": {
    "available": true,
    "reason": null
  },
  "daily_reminders_available": true,
  "bills_plans": false,
  "created_at": 1727600000
}

Retrieve an app

GET/v1/apps/{appID}

Retrieves the app your secret key belongs to.

Returns the app object. If no app has that ID, or the key belongs to another app, returns 404 with code not_found.

GET /v1/apps/{appID}
curl https://api.abuna.app/v1/apps/8ddhXCDW \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "id": "8ddhXCDW",
  "team_id": "01J9ZQ3A1B2C3D4E5F6G7H8J9K",
  "name": "My store",
  "slug": "my-store-test",
  "environment": "test",
  "project_id": "Q7mKp2Rt",
  "live_app_id": "Q7mKp2Rt",
  "test_app_id": "8ddhXCDW",
  "base_currency": "XAF",
  "grace_period_days": 3,
  "renewal_lead_days": 3,
  "invoice_prefix": "MYST",
  "customer_cancel": "at_period_end",
  "publishable_key": "pk_test_...",
  "secret_key_prefix": "sk_test_3f9c1a2b",
  "webhook_url": "https://example.com/webhooks",
  "webhook_events": ["session.completed", "subscription.paid", "subscription.canceled", "invoice.paid"],
  "webhook_configured": true,
  "webhook_tested": true,
  "success_url": null,
  "cancel_url": null,
  "support_email": "support@example.com",
  "support_url": null,
  "terms_url": null,
  "timezone": "Africa/Douala",
  "branding": {
    "accent_color": "#1F6FEB"
  },
  "telegram_updates": true,
  "whatsapp_updates": false,
  "daily_reminders": false,
  "payments": {
    "ready": true,
    "email_verified": true,
    "provider_connected": true,
    "support_contact": true,
    "providers_available": true,
    "webhook_confirmed": true,
    "webhook_received": true,
    "provider_name": null,
    "account_id": null,
    "account_name": null,
    "abuna_payments": {
      "available": false,
      "enabled": false
    }
  },
  "read_only": false,
  "whatsapp_availability": {
    "available": true,
    "reason": null
  },
  "daily_reminders_available": true,
  "bills_plans": false,
  "created_at": 1727600000
}

Next steps