Subscriptions

A subscription starts from a product with a monthly or yearly price. The buyer pays for it on the hosted checkout or on the checkout embedded in your site, and their card is charged again every cycle. AgentaOS is the merchant of record: it adds VAT where the buyer owes it, takes the payment, and issues the invoice for every cycle. You create the plan once. Each buyer who pays for it starts their own subscription, and you see each one under Subscriptions in the dashboard. For a step-by-step first sale, see Sell a subscription.

Create a plan

In the dashboard, go to Products and click New product. Under Pricing, click Subscription, then pick Monthly or Yearly. The price you type is the plan price before VAT, unless you tick Prices include VAT. Below the price, the form shows what buyers pay. For a €29 plan it reads “EU consumers pay €35.96 (€29.00 + €6.96 VAT), you receive €29.00 before fees. Everyone else pays €29.00.”

The Pricing section of Create a new product: price €29, EUR, Subscription and Monthly selected, Free trial (days) set to 14, and Trial price left empty. — Pricing for a monthly plan at €29 with a 14-day free trial.

Click Create product. The plan gets a link that you send to buyers, and a link ID that your code uses. Make one product for each price: a monthly Pro plan and a yearly Pro plan are two products. Changing a plan’s price applies to new subscriptions only. A running subscription keeps the price it started on.

One buyer, several subscriptions

One email can hold several active subscriptions on the same plan at once, for example one person paying for several teams. AgentaOS keeps one customer record for the email and a separate subscription for each payment, with no limit. If your product allows one subscription per account, enforce it on your side: the first checkout.session.completed carries your metadata and the subscription’s id in metadata.subscriptionId, so keep that pair and show the link only to a buyer who has no active subscription. The subscriptions list is paged only; it cannot be filtered by email or by link.

Subscription statuses

A subscription moves through these statuses. The dashboard shows the status on each subscription, and the API returns it as status.

Status	When
`incomplete`	The buyer started the checkout but did not finish paying or saving a card.
`trialing`	The buyer started a free trial. Their card is saved and nothing is charged.
`active`	The first payment went through. The card is charged again at the start of each cycle.
`past_due`	A renewal charge failed and the charge is retried.
`canceled`	The subscription ended. There are no more charges.

The dashboard shows the next charge date under Renews. Each paid cycle produces an invoice. The SDK reference lists every status, including the rare ones.

Free trials

A trial belongs to the plan. Type the number of days in Free trial (days), from 1 to 730. At checkout the buyer sees €0.00 due today and the price that follows the trial.

The checkout for the Pro plan. Due today is €0.00, the note says €35.96 a month after the 14-day free trial, and the button reads Start 14-day free trial. — The buyer saves a card and pays nothing today.

The €35.96 is the €29.00 plan price plus 24% VAT, the Estonian rate. The checkout charges it to every EU consumer while AgentaOS sells under the EU distance-selling threshold. See How tax works. When the buyer clicks Start 14-day free trial, their card is saved and the subscription starts as trialing. The first charge happens when the trial ends. The buyer and you each get an email when the trial starts. To charge for the trial instead of giving it free, type an amount in Trial price. That amount covers the whole trial, and the buyer pays it at checkout.

The checkout.session.completed webhook for a free trial has amount "0", trial: true, and trial_end. Treat it as “trial started”, not as money received. See Webhook events.

Upgrade and downgrade

To move a subscriber to another plan, open the subscription and click Change plan. Pick the new plan. The dialog shows what the change costs before you confirm it.

The Change plan dialog with Pro Plus at €49.00 a month selected. It shows Due today €0.00 (incl. VAT), then €60.76 a month starting Oct 12, 2026. — An upgrade from Pro to Pro Plus during a trial.

Upgrade (the new plan costs more): the buyer pays the prorated difference today on their saved card, and the new plan applies at once. During a free trial nothing has been paid yet, so the amount due today is €0.00.
Downgrade (the new plan costs the same or less): nothing is charged today. The buyer keeps the current plan until the current period ends, and then the new plan starts.

A scheduled downgrade shows on the subscription as Scheduled change until it takes effect.

The Plan section of a subscription. Scheduled change reads Pro (€35.96/mo) from Oct 12, 2026. — A downgrade to Pro, scheduled for the end of the period.

To undo a scheduled downgrade, click Change plan and pick the current plan. The dashboard labels it “current plan”, and choosing it cancels the scheduled change without a charge. A plan change keeps the currency and the billing interval. You can move a monthly EUR plan only to another monthly EUR plan. The subscription must be trialing or active.

Cancel

Click Cancel subscription on the subscription page and confirm. The subscription stays active until the end of the current period, and then it ends. The buyer keeps what they paid for, and nothing is refunded.

Until the period ends, Resume subscription undoes the cancellation. A subscription always runs to the end of the period it is in; it cannot be ended earlier. You can schedule a cancellation while a dispute on one of its charges is open; the cancellation and the dispute do not affect each other.

Credits

A credit takes money off a subscriber’s next invoice, for example to make up for two days of downtime. It is not a refund: no money goes back to the card, and receipts already sent stay as they are. The credit comes out of what you earn on that invoice. To give one, open the subscription and click Give credit under Credit. Type the Amount and a Reason, then click Confirm credit. The form says of the reason: “The subscriber never sees this. It is what you and your team read later.”

The panel then shows what the next invoice will charge.

The Credit section reads: €10.00 credited. It comes off their next invoice on Oct 12, 2026, leaving €50.76 to pay. — The credit and the smaller next invoice.

A credit can cover the whole next invoice, and no more.
The subscription must be active or trialing, not scheduled to cancel, and without a scheduled plan change.
While a subscriber has credit left, a plan change waits until their next invoice.
The unspent credit belongs to the buyer, and it is shared by every subscription they have with you.
Only an owner or admin can give or see credits. An API key cannot.

The buyer pays less on their next charge. When a credit covers a whole month, their receipt says the credit covered it and nothing was charged to the card.

Discount codes

A buyer can type a discount code at checkout. On a subscription, the discount applies to the first invoice only, and every renewal charges the full price. The subscription records which code the buyer used, so you can list the subscribers each code brought in. See Discount codes.

Emails and receipts for the buyer

A receipt email for every paid cycle, with the receipt attached as a PDF. AgentaOS issues it as the merchant of record, and the subscription page lists each paid cycle under Billing history. See Invoices and Receipts.
An email when a free trial starts.

From code

For a signed-in user who upgrades inside your app, see the runnable demo on Paywall for logged-in users. The same actions are in the SDK (@agentaos/pay) and the CLI (agenta). The SDK needs an API key: const agentaos = new AgentaOS(process.env.AGENTAOS_API_KEY!). Code uses the subscription id that subscriptions list returns.

# Create a monthly plan with a 14-day free trial
agenta products create --name "Pro" -a 29 -c EUR --subscription --interval month --trial-days 14

# List subscriptions
agenta subscriptions list --limit 20

# Quote a plan change, then apply it
agenta subscriptions change-plan <subscriptionId> --to <linkId> --dry-run
agenta subscriptions change-plan <subscriptionId> --to <linkId>

# Cancel at the end of the period
agenta subscriptions cancel <subscriptionId>

# Give a €10 credit, then list the credits given
agenta subscriptions credit <subscriptionId> -a 10 --reason "Two days of downtime"
agenta subscriptions credits <subscriptionId>

// Create a monthly plan with a 14-day free trial
const plan = await agentaos.paymentLinks.create({
  name: 'Pro',
  amount: 29,
  currency: 'EUR',
  type: 'subscription',
  billingInterval: 'month',
  trialPeriodDays: 14,
});
// plan.id is the link ID; plan.checkoutUrl is the link for buyers

// List subscriptions
const page = await agentaos.subscriptions.list({ limit: 20 });

// Quote a plan change, then apply it with the quote's prorationDate
const quote = await agentaos.subscriptions.previewPlanChange(subscriptionId, proPlusLinkId);
const change = await agentaos.subscriptions.changePlan(subscriptionId, {
  targetLinkId: proPlusLinkId,
  prorationDate: quote.prorationDate,
});

// Cancel at the end of the period
const cancel = await agentaos.subscriptions.cancel(subscriptionId);

// Give a €10 credit (minor units), then list the credits given
const credit = await agentaos.subscriptions.credit(subscriptionId, {
  amountMinor: 1000,
  reason: 'Two days of downtime',
  idempotencyKey: randomUUID(), // from node:crypto; reuse the same key on a retry
});
const credits = await agentaos.subscriptions.credits(subscriptionId);

The quote has direction (upgrade, downgrade, or revert), dueTodayMinor, nextInvoiceMinor, and nextInvoiceAt. Amounts that end in Minor are in minor units: 4900 is €49.00. Show the quote to the person who approves the change before you apply it, because an upgrade charges the card. Credits need an owner or admin who is signed in, through agenta login or the dashboard session: an API key is refused. Every field is in the reference: SDK subscriptions and CLI subscriptions.

Next steps

Sell a subscription

Create a plan, take the first subscriber, change their plan, and cancel.

Discount codes

Take money off the first invoice, or track who sent a buyer.

Embedded checkout

Show the checkout on your own page.

Webhook events

React to trials, renewals, failed payments, and plan changes.

Getting started

Grow

Build with AI agents

Integrations

Sell

Platforms

Merchant of Record

Payouts

Webhooks

For customers

Create a plan

One buyer, several subscriptions

Subscription statuses

Free trials

Upgrade and downgrade

Cancel

Credits

Discount codes

Emails and receipts for the buyer

From code

Next steps

Sell a subscription

Discount codes

Embedded checkout

Webhook events

​Create a plan

​One buyer, several subscriptions

​Subscription statuses

​Free trials

​Upgrade and downgrade

​Cancel

​Credits

​Discount codes

​Emails and receipts for the buyer

​From code

​Next steps

Sell a subscription

Discount codes

Embedded checkout

Webhook events

Create a plan

One buyer, several subscriptions

Subscription statuses

Free trials

Upgrade and downgrade

Cancel

Credits

Discount codes

Emails and receipts for the buyer

From code

Next steps