Subscriptions

const product = await agentaos.paymentLinks.create({
  amount: 29.99,
  currency: 'EUR',
  description: 'Pro',
  type: 'subscription',
  billingInterval: 'month',
});

// Logged-in user: create a checkout from the product's linkId
const checkout = await agentaos.checkouts.create({
  linkId: product.id,
  buyerEmail: user.email,
  buyerCountry: user.country,
  metadata: { customerId: user.id },
});

const page = await agentaos.subscriptions.list({
  limit: 20,   // default 20, max 100
  offset: 0,
});
console.log(page.total, page.hasMore);

import type { Subscription } from '@agentaos/pay';

async function findSubscription(subscriptionId: string): Promise<Subscription | undefined> {
  for (let offset = 0; ; offset += 100) {
    const page = await agentaos.subscriptions.list({ limit: 100, offset });
    const found = page.items.find((s) => s.id === subscriptionId);
    if (found || !page.hasMore) return found;
  }
}

{
  "id": "b7e2a1c4-...",
  "customerEmail": "jane@example.com",
  "customerName": "Jane Doe",
  "planName": "Pro plan: monthly",
  "billingInterval": "month",
  "status": "active",
  "unitAmountMinor": 1999,
  "currency": "EUR",
  "currentPeriodEnd": "2026-09-06T00:00:00.000Z",
  "stripeSubscriptionId": "sub_1H...",
  "linkId": "4cbb8f52-7cf2-4480-8c66-34f794cd23d0"
}

const invoices = await agentaos.subscriptions.invoices(sub.id);

const product = await agentaos.paymentLinks.create({
  amount: 29,
  currency: 'EUR',
  description: 'Pro, monthly',
  type: 'subscription',
  billingInterval: 'month',
  trialPeriodDays: 14,
});

const quote = await agentaos.subscriptions.previewPlanChange(sub.id, PRO_PLUS_LINK_ID);
// quote.direction      'upgrade' | 'downgrade' | 'revert'
// quote.dueTodayMinor  charged now (0 for a downgrade)
// quote.effectiveAt    upgrade: now; downgrade: the current period end
// quote.prorationDate  pass it to changePlan

const result = await agentaos.subscriptions.changePlan(sub.id, {
  targetLinkId: PRO_PLUS_LINK_ID,
  prorationDate: quote.prorationDate,
});

switch (result.direction) {
  case 'upgrade':
    console.log(result.status, result.unitAmountMinor); // charged now, e.g. 'active' 4900
    break;
  case 'downgrade':
    console.log(result.effectiveAt, result.unitAmountMinor); // when the cheaper plan starts
    break;
  case 'revert':
    console.log(result.unitAmountMinor); // the pending downgrade is canceled, the plan stays
    break;
}

await agentaos.subscriptions.cancel(sub.id);

{
  "status": "active",
  "currentPeriodEnd": "2026-09-06T00:00:00.000Z",
  "cancelAtPeriodEnd": true,
  "effectiveCancelDate": "2026-09-06"
}

import { randomUUID } from 'node:crypto';

const credit = await agentaos.subscriptions.credit(sub.id, {
  amountMinor: 1000, // €10.00 in the plan's currency
  reason: 'Two days of downtime',
  idempotencyKey: randomUUID(),
});
credit.nextInvoiceDueAfterCreditMinor; // what the next invoice will charge

const { items, balanceMinor } = await agentaos.subscriptions.credits(sub.id);