Skip to main content
A subscription is a running, recurring commitment: card on file, billed automatically every cycle. AgentaOS manages the billing for you (retries on failed cards, prorations, cancellations) via our card processor under the hood.
There is no subscriptions.create(). Subscriptions are created by the buyer, not by you. You create a payment link with type: 'subscription', the buyer pays it at the hosted checkout, and that payment starts the subscription. This resource is the merchant-side management surface: list what’s running, cancel what shouldn’t be.

​
How a subscription gets created

1

Create a subscription payment link

2

Share checkoutUrl

The buyer opens plan.checkoutUrl and pays with a card at the hosted checkout, exactly like a one-time payment.
3

First cycle books, subscription goes active

AgentaOS creates a customer and subscription with our card processor behind the scenes, charges cycle 1, and the subscription becomes visible to subscriptions.list().
4

Renews automatically

Every billingInterval, the card on file is charged again. No action from you unless the charge fails or the buyer cancels.

​
Money model: unitAmountMinor

Every other amount in this API is decimal currency units (amount: 49.99 means €49.99). Subscriptions are the one exception: unitAmountMinor is an integer of the smallest currency unit, mirroring how our card processor represents recurring prices internally.
The field name is the signal: anything ending in Minor is an integer of cents/pence, not decimal currency. Everywhere else in this API (payment links, checkouts, invoices), a plain amount is already in currency units, no conversion needed.

​
Statuses

status is the raw subscription status from the card processor, passed through unchanged:

​
List subscriptions

Paginated: every list call returns { items, total, hasMore }.

​
Cancel a subscription

Defaults to cancel-at-period-end: the buyer keeps what they already paid for until currentPeriodEnd, and there’s no refund. Pass atPeriodEnd: false to cancel immediately instead. Calling cancel on an already-canceled subscription is a no-op, safe to retry.
Cancellation never issues a refund. It only stops future renewals. If you owe the buyer money back for the current period, that’s a separate, manual step on your side.

​
Response

Subscription object (from list):
​
string
Subscription UUID.
​
string | null
Subscriber email.
​
string | null
Subscriber name.
​
string | null
The plan’s name or description, from the payment link.
​
string | null
month or year.
​
string
One of the statuses above.
​
number
Per-cycle amount in integer minor units (e.g. 1999 = €19.99).
​
string
Settlement currency.
​
string | null
ISO 8601 end of the current paid period. null before the first cycle books.
​
string | null
Underlying subscription ID from the card processor.
Cancel result:
​
string
Status after cancellation.
​
string | null
ISO 8601 end of the current paid period.
​
boolean
Whether the subscription is scheduled to end at period end.
​
string | null
ISO date the cancellation takes effect.

​
Next steps

Payment links

Create the type: 'subscription' link that starts this flow.

Customers

See who’s subscribed to you.

Invoices

Every renewal charge issues its own invoice.

Webhooks

Get notified when a subscription payment lands.