Free trials

Give customers free access before their first paid billing period, without charging them at checkout.

Set a trial on a price

Create a price with trial_days, an integer from 1 to 365. This example offers 14 days free, then FCFA 5,000 a month.

curl https://api.abuna.app/v1/apps/8ddhXCDW/prices \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "pR4dWx9K",
    "name": "Monthly",
    "currency": "XAF",
    "amount": 5000,
    "interval": "month",
    "trial_days": 14
  }'

Omit trial_days or send null for no trial. The trial length cannot change after the price is created. Create another price for a different default.

Send the customer to checkout

Create a checkout session from your server, then send the customer to its url. Replace the example IDs and secret key with your Test values.

curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-user-42-trial-1" \
  -d '{
    "type": "checkout",
    "price_id": "Zt6YbN3q",
    "customer_id": "Cu5tM8rA",
    "success_url": "https://example.com/subscribed?session_id={SESSION_ID}",
    "cancel_url": "https://example.com/plans",
    "metadata": {"user_id": "42"}
  }'

The customer confirms their contact details, chooses reminders and agrees to start the trial. Abuna then emails them a 6-digit code, and the trial starts once they enter it on the checkout page. Until then, no subscription exists and no trial is used. Nothing is charged. The checkout completes and takes them to your success_url, with the usual reminder-channel setup.

Start a trial without checkout

For an existing customer, create a subscription directly. This example overrides the price's default with 7 days.

curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: subscription-user-42-trial-1" \
  -d '{
    "customer_id": "Cu5tM8rA",
    "price_id": "Zt6YbN3q",
    "trial_days": 7,
    "metadata": {"user_id": "42"}
  }'

The subscription starts with status: trialing. Its trial_ends_at is the end of the trial, in Unix seconds. Without a trial, that field is null.

{
  "id": "x9QbL2sK",
  "app_id": "8ddhXCDW",
  "customer_id": "Cu5tM8rA",
  "price_id": "Zt6YbN3q",
  "status": "trialing",
  "starts_at": 1727600000,
  "activated_at": 1727600000,
  "trial_ends_at": 1728204800,
  "canceled_at": null,
  "cancel_at": null,
  "cancel_at_period_end": false,
  "current_period_start": 1727600000,
  "current_period_end": 1728204800,
  "ended_reason": null,
  "metadata": {
    "user_id": "42"
  },
  "created_at": 1727600000,
  "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b"
}

Grant access from webhooks

Verify webhook signatures before using an event. Use the subscription in the event, not the browser redirect, to decide access.

• subscription.created is sent when a trial starts. A trial checkout also sends session.completed. Grant access when data.subscription.status is trialing; data.subscription.trial_ends_at is when the trial ends.
• subscription.paid is sent once the customer pays the first invoice, during or after the trial.
• subscription.trial_ending tells you the trial is ending, at your app's normal renewal reminder lead time. If you set up your webhook URL before free trials existed, turn this event on first: open Webhooks in the dashboard and edit Events.
• Keep access during active and past_due. Stop access on subscription.canceled.

The first payment

The first paid period starts at trial_ends_at, even if the customer pays early. Abuna sends its invoice and pay link using your app's renewal lead time.

The pay-by date is normally the trial end plus your app's grace_period_days, capped at the paid period's end. Use the invoice's due_at for the exact deadline, including when the invoice arrives later.

Customers get 3 days to pay by default; you can set 1 to 14. Nothing is taken automatically.

If the invoice remains unpaid, the subscription follows the usual unpaid renewal rules, including cancellation after the pay-by date.

Cancel during a trial

A customer who cancels during the trial keeps access until the trial ends. Any unpaid first invoice is canceled, so nothing remains to pay. A scheduled cancel sets cancel_at to trial_ends_at.

From the cancel API, at_period_end: true schedules that same end. Omit it or send false to end access immediately.

Test and Live limits

Customers with a trialing subscription, which starts once they confirm their email, count toward your team's Live subscriber limit. Test mode has no subscriber limit.