Subscriptions quickstart

Create a recurring priceCopy Anchor Link

In the dashboard, add a product and give it a recurring price. A recurring price charges every 30 days or every 365 days. Prices are never edited: to change one, add a new price and archive the old one.

Copy the price's id (fian_price_…) from the prices table and put it in your server's environment, for example as FIANTO_PRICE_PRO.

Create a subscription sessionCopy Anchor Link

Change your checkout route to send mode: 'subscription' and the recurring price_id. Leave out amount and description: the price sets the amount, and its product's name becomes the description.

// app/api/checkout/route.ts
import { Checkout } from '@fianto/nextjs';

export const POST = Checkout({
  createSession: async () => {
    const priceId = process.env.FIANTO_PRICE_PRO;
    if (!priceId) return new Response('Plan not configured', { status: 500 });

    return {
      mode: 'subscription',
      order_id: `sub_${crypto.randomUUID()}`, // use your own id for this sign-up
      price_id: priceId,
      success_url: 'https://shop.example/thank-you',
      cancel_url: 'https://shop.example/pricing',
    };
  },
  onError: (error) => console.error(error),
});

Set your button's label to subscribe. Nothing else on the page changes.

The first subscription session for a price creates its plan on Solana; Fianto pays for that. Until the plan is on chain, the checkout page shows it as preparing (plan_status: preparing) instead of a pay button. Fianto retries a failed plan creation after 30 seconds, 2 minutes, 10 minutes and 1 hour, then marks it failed.

Handle the subscription webhooksCopy Anchor Link

Fianto sends subscription.created when the subscribe transaction is finalized. Give access there, and keep it in step with the other subscription events.

// app/api/webhooks/fianto/route.ts
import { Webhooks } from '@fianto/nextjs';

export const POST = Webhooks({
  secret: process.env.FIANTO_WEBHOOK_SECRET,
  // Dedupe on event.id in the same database transaction as each change.
  onSubscriptionCreated: async (event) => {
    console.log('grant access', event.data.id, event.data.order_id);
  },
  onSubscriptionRenewed: async (event) => {
    console.log('extend access', event.data.id, event.data.current_period_end);
  },
  onSubscriptionPastDue: async (event) => {
    console.log('renewal failing', event.data.id);
  },
  onSubscriptionEnded: async (event) => {
    console.log('remove access', event.data.id, event.data.end_reason);
  },
});

The seven subscription events are subscription.created, subscription.renewed, subscription.payment_failed, subscription.past_due, subscription.cancel_scheduled, subscription.cancel_withdrawn and subscription.ended. A subscription session creates no order, so fulfil subscriptions from these events.

Cancel from your serverCopy Anchor Link

Cancel with the API, now or at the end of the current period. A cancel at now sends subscription.ended; a cancel at period_end sends subscription.cancel_scheduled.

import { Fianto } from '@fianto/sdk';

const fianto = new Fianto(); // reads FIANTO_APP_ID and FIANTO_APP_SECRET

export async function cancelAtPeriodEnd(subscriptionId: string) {
  return fianto.subscriptions.cancel(subscriptionId, { at: 'period_end' });
}