Subscriptions - AgentaOS

agentaos.subscriptions is a read/manage surface, not a creation API. A subscription comes into existence when a buyer pays a payment link created with type: 'subscription', AgentaOS bills them every billingInterval from then on through Merchant of Record (card or bank). There is no subscriptions.create(): to start recurring billing, create a subscription payment link and let the buyer check out.

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 },
});

See Sell a subscription.

`subscriptions.list(params?)`

Mirrors the dashboard’s Subscriptions list, scoped to the environment (test or live) your API key belongs to.

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

number

default:"20"

Max 100.

number

default:"0"

Returns PaginatedList<Subscription>.

Subscription fields

string

Subscription UUID.

string | null

The product name or description.

'month' | 'year' | null

SubscriptionStatus

See statuses below.

number

Per-cycle amount in integer minor units. 1999 means €19.99. This is the one field in the entire SDK named *Minor, see the money model.

string

string | null

ISO 8601. null before the first billing cycle has booked.

string | null

The underlying subscription ID from the card processor.

string

Same UUID as checkouts.create({ linkId }) / product page Copy link ID.

object | null

Null unless a downgrade is scheduled. Then { linkId, planName, unitAmountMinor, effectiveAt }: the plan the subscription switches to at effectiveAt (the period end). planName, unitAmountMinor and linkId above stay what the buyer paid for until then, so gate access on them, not on the pending change.

boolean

string | null

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

Statuses

SubscriptionStatus is the raw subscription status from the card processor, mirrored onto the local record by AgentaOS’s polling reconciliation (there are no inbound webhooks from the card processor in this system, statuses update on the next poll cycle):

Status	Meaning
`incomplete`	First payment attempt hasn’t succeeded yet.
`incomplete_expired`	First payment never completed within the window; subscription never activated.
`trialing`	In a trial period, no charge yet.
`active`	Billing normally.
`past_due`	A renewal charge failed; the card processor is retrying.
`canceled`	Ended, no further charges.
`unpaid`	Renewal retries exhausted without a successful charge.
`paused`	Billing paused (e.g. a trial-without-payment-method configuration ending).

`subscriptions.invoices(id)`

Each billing cycle’s invoice, newest first.

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

string

number

Currency units.

string

boolean

Free trials

A trial is a property of the product, not of the subscription: create the plan with trialPeriodDays (1 to 730). At checkout the buyer’s card is saved with nothing due today, the subscription is created as trialing, and the first charge happens when the trial ends, after which it is active.

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

What you observe:

checkout.session.completed fires when the card is saved, with amount: "0", trial: true and trial_end (ISO 8601) on event.data. Treat it as “trial started”, not as money received.
subscriptions.list() shows status: 'trialing' and the plan’s unitAmountMinor; currentPeriodEnd is the trial end while trialing.
Cancelling during the trial stops it before any charge.

`subscriptions.previewPlanChange(id, targetLinkId)`

Quote moving a subscription to another plan. Read-only: nothing is charged or scheduled. The target must be a different subscription product in the same currency and billing interval, and the subscription must be active or trialing; anything else is a 400.

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

'upgrade' | 'downgrade'

upgrade when the new plan costs more per cycle.

string

number

Integer minor units charged now. Always 0 for a downgrade.

number

string

ISO 8601. Upgrade: now. Downgrade: the current period end.

number

The next regular cycle invoice on the new plan, integer minor units.

number

string

ISO 8601.

number

Unix seconds. Echo it in changePlan so the charge matches this quote.

`subscriptions.changePlan(id, { targetLinkId, prorationDate })`

Apply a quoted plan change. An upgrade charges the prorated difference on the saved card now; a downgrade charges nothing today and switches at the current period end. Idempotent on (subscription, target plan, prorationDate).

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

if (result.direction === 'upgrade') {
  result.status;          // 'active'
  result.unitAmountMinor; // new per-cycle amount, e.g. 4900
} else {
  result.effectiveAt;     // when the cheaper plan starts
  result.unitAmountMinor;
}

Show the quote to the merchant (or the subscriber) before calling this: the upgrade charge is real money. The CLI does both steps in one command: agenta subscriptions change-plan <id> --to <linkId> (add --dry-run for the quote only). Cancelling a scheduled downgrade. Change the plan to the current plan again. The preview and the result come back with direction: 'revert', nothing is charged, and pendingPlanChange is null afterwards. Targeting the plan that is already pending returns 400 (“already scheduled”). Webhooks. Every plan change fires subscription.updated on the organization endpoint: when a downgrade is scheduled (data.pending_plan is set), when it is reverted (pending_plan back to null), when an upgrade is applied, and when the scheduled plan takes over at the period end. See Events.

`subscriptions.cancel(id)`

Cancels at period end. The subscriber keeps access until currentPeriodEnd. No refund. Calling it again is a no-op. Pass { atPeriodEnd: false } to cancel immediately instead.

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

Response

SubscriptionStatus

Status after the cancellation call.

string | null

ISO 8601.

boolean

Whether it’s scheduled to cancel at period end vs. already canceled.

string | null

ISO 8601 date the cancellation takes (or took) effect.

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

Next steps

Sell a subscription

Create a product, share the link or check out a logged-in user.

Payment links

Create the type: 'subscription' link that gives birth to a subscription.

Customers

The people paying your subscriptions.

Invoices

Each renewal charge issues its own invoice.

Errors

What cancel() throws on an unknown subscription ID.

​subscriptions.list(params?)

​Subscription fields

​Statuses

​subscriptions.invoices(id)

​Free trials

​subscriptions.previewPlanChange(id, targetLinkId)

​subscriptions.changePlan(id, { targetLinkId, prorationDate })

​subscriptions.cancel(id)

​Response

​Next steps

Sell a subscription

Payment links

Customers

Invoices

Errors

`subscriptions.list(params?)`

Subscription fields

Statuses

`subscriptions.invoices(id)`

Free trials

`subscriptions.previewPlanChange(id, targetLinkId)`

`subscriptions.changePlan(id, { targetLinkId, prorationDate })`

`subscriptions.cancel(id)`

Response

Next steps