Sell a Subscription

By the end of this guide you’ll have a subscription product, a test subscriber, and you’ll know how to see who’s subscribed and cancel them. This runs in test mode. The “buyer” is you, paying with the test card.

There is no subscriptions.create(). You create a product once. The buyer pays. That payment is what starts the subscription.

Before you start

An AgentaOS account and a test API key (sk_test_...) from Settings → Developers → API Keys. See Accept your first payment if you haven’t.
Card and bank are on by default. Wallet-only accounts cannot sell subscriptions. KYB is only needed for live. See Go live.

Test card, typed on the hosted page only: 4242 4242 4242 4242, any future expiry, any CVC. Never send a card number to the API.

The one id

The dashboard calls this a product. The API creates it with paymentLinks.create. The id you pass around is linkId.

Name	What it is	Where you see it
`linkId`	The product’s UUID	Product page → Copy link ID, or `product.id`
Buyer link	`/pay/…` URL	Product page → Copy link. Anyone can open this.
`sessionId`	One checkout attempt	`checkouts.create` → `checkout.sessionId`

linkId is what checkouts.create({ linkId }) wants. It is not the /pay/… slug.

Create the product once

One product per price. Catalog → Products, or in code:

SDK
cURL

import { AgentaOS } from '@agentaos/pay';

const agentaos = new AgentaOS(process.env.AGENTAOS_API_KEY!); // sk_test_...

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

// product.id is the linkId
// product.checkoutUrl is the /pay/… buyer link

curl -X POST https://api.agentaos.ai/api/v1/gateway/payment-links \
  -H "x-api-key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 19.99,
    "currency": "EUR",
    "description": "Pro, monthly",
    "type": "subscription",
    "billingInterval": "month"
  }'

amount: 19.99 means €19.99, not cents. Create this once, not once per buyer.

From the terminal: agenta products create --name "Pro" -a 19.99 -c EUR --subscription --interval month --json returns the same product; its id is the linkId. Needs agentaos 2.1 or newer (npm install -g agentaos@latest). agenta pay checkout still only makes a one-time checkout.

Get them to pay

Two ways. Same product. Same linkId.

Anyone (share the link)
Logged-in user

They already have an account in your app. Create a checkout from linkId and pass your user id:

const checkout = await agentaos.checkouts.create({
  linkId: product.id,
  buyerEmail: user.email,
  buyerCountry: user.country, // ISO-2, e.g. 'DE'
  metadata: { customerId: user.id },
});

// Save checkout.sessionId as pending.
// Redirect them to checkout.checkoutUrl

buyerEmail should match their profile. That is how AgentaOS attaches the customer.Do not send them the /pay/… link. That page has no metadata.customerId.Store linkId on the product, your user id in your database, and after they pay the AgentaOS subscription.id.

Field	Value
Card number	`4242 4242 4242 4242`
Expiry	Any future date
CVC	Any 3 digits

Confirm they paid

Shared the /pay/… link? List subscriptions and find them by email:

const page = await agentaos.subscriptions.list({ limit: 20, offset: 0 });
const sub = page.items.find((s) => s.customerEmail === 'you@example.com');
console.log(sub?.status);          // 'active'
console.log(sub?.unitAmountMinor); // 1999

agenta subscriptions list --json

Created a checkout for a logged-in user? Prefer the webhook. checkout.session.completed includes event.data.metadata. Your customerId is there. So is subscriptionId after they start the card form.

case 'checkout.session.completed': {
  const { sessionId, metadata } = event.data;
  const customerId = metadata?.customerId as string | undefined;
  const subscriptionId =
    typeof metadata?.subscriptionId === 'string' ? metadata.subscriptionId : null;

  if (!customerId || !subscriptionId) break;

  // Save subscriptionId on your user (customerId).
  // Key idempotency on sessionId.
  break;
}

subscriptions.list() does not copy your metadata. Later renewals fire the same event without customerId. Look up the user by the subscription.id you stored the first time.Or poll checkouts.retrieve(sessionId) until completed, expired, or cancelled. Verify the signature: Handle webhooks.

unitAmountMinor is cents. 1999 means €19.99. Every other amount in this API is already decimal (19.99).

Status, invoices, cancel

Use the subscription.id.

const page = await agentaos.subscriptions.list({ limit: 100 });
const sub = page.items.find((s) => s.id === subscriptionId);

sub?.status; // active | trialing | past_due | canceled | ...
sub?.cancelAtPeriodEnd;
sub?.currentPeriodEnd;

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

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

Cancel does not refund. It stops the next renewal. They keep access until currentPeriodEnd. Pass { atPeriodEnd: false } (CLI: --now) to cancel immediately instead. Calling cancel again is a no-op.PDF: agentaos.invoices.downloadPdf(invoice.id) and agentaos.invoices.getReceipt(invoice.id).

CLI
cURL

agenta subscriptions cancel 7c1e9b2a-4f6d-4a3b-9c8e-2d5f0a1b3c4d

curl -X POST https://api.agentaos.ai/api/v1/gateway/subscriptions/7c1e9b2a-4f6d-4a3b-9c8e-2d5f0a1b3c4d/cancel \
  -H "x-api-key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "atPeriodEnd": true }'

Optional: a free trial

A trial is a property of the plan. Add trialPeriodDays (1 to 730) when you create it; nothing else changes.

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

agenta products create --name "Pro" -a 19.99 -c EUR --subscription --interval month --trial-days 14 --json

The hosted checkout says “Due today €0.00, then €19.99/mo after your 14-day free trial”, saves the card, and creates the subscription as trialing. The first charge happens when the trial ends. checkout.session.completed fires at trial start with amount: "0", trial: true and trial_end; treat it as “trial started”, not as money received.

Optional: upgrade or downgrade

Each price is its own product. To move a subscriber, quote the change, show it, then apply it with the quote’s prorationDate.

const quote = await agentaos.subscriptions.previewPlanChange(sub.id, PRO_PLUS_LINK_ID);
// quote.direction 'upgrade' | 'downgrade', quote.dueTodayMinor, quote.effectiveAt

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

agenta subscriptions change-plan <subscriptionId> --to <linkId> --dry-run --json   # quote only
agenta subscriptions change-plan <subscriptionId> --to <linkId> --json             # quote, then apply

An upgrade charges the prorated difference on the saved card now and the new price applies immediately. A downgrade charges nothing today; the subscriber keeps the current plan until effectiveAt, the current period end, and the subscription reports the switch as pendingPlanChange until then. To cancel a scheduled downgrade, change the plan to the current plan again (direction: 'revert', nothing charged). The target must be a different plan in the same currency and billing interval, and the subscription must be active or trialing. Each of these fires subscription.updated.

Verify it worked

subscriptions.list() shows status: 'active' and the right unitAmountMinor.
Shared-link buyer: they used /pay/… and appear under Customers.
Logged-in buyer: they landed on /checkout/…. The webhook has metadata.customerId and metadata.subscriptionId. subscriptions.list() does not contain customerId.
Cancel sets cancelAtPeriodEnd: true. Access stays until currentPeriodEnd.

Next steps

Handle webhooks

Verify the signature and handle the same event twice.

Checkouts

checkouts.create({ linkId }) and every field on the session.

Subscriptions

List, invoices, and cancel.

Go live

Take this product from test mode to real money.

​Before you start

​The one id

​Verify it worked

​Next steps

Handle webhooks

Checkouts

Subscriptions

Go live

Before you start

The one id

Verify it worked

Next steps