Subscriptions

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.

// This is how a subscription is born, on the hosted checkout, not the SDK:
const link = await agentaos.paymentLinks.create({
  amount: 29.99,
  currency: 'EUR',
  description: 'Pro plan: monthly',
  type: 'subscription',
  billingInterval: 'month',
});
// → share link.checkoutUrl. Every buyer who pays it gets their own 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 plan’s name/description, taken from the subscription payment link.

'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.

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

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.cancel(id, params?)`

Defaults to cancel-at-period-end: the subscriber keeps access through the period they already paid for, no refund. Pass { atPeriodEnd: false } to cancel immediately instead. Calling it again on an already-canceled subscription is a no-op, not an error.

// Cancel at period end (default): subscriber keeps access until currentPeriodEnd
await agentaos.subscriptions.cancel('sub_...');

// Cancel immediately: access revoked now, no refund
await agentaos.subscriptions.cancel('sub_...', { atPeriodEnd: false });

boolean

default:"true"

true schedules cancellation for currentPeriodEnd. false cancels now.

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

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.

SDK

CLI

API Reference

`subscriptions.list(params?)`

Subscription fields

Statuses

`subscriptions.cancel(id, params?)`

Response

Next steps

Payment links

Customers

Invoices

Errors

​subscriptions.list(params?)

​Subscription fields

​Statuses

​subscriptions.cancel(id, params?)

​Response

​Next steps

Payment links

Customers

Invoices

Errors

`subscriptions.list(params?)`

Subscription fields

Statuses

`subscriptions.cancel(id, params?)`

Response

Next steps