Skip to main content
This page is for developers adding paid tiers to an agent. It covers reading the plan claim, enforcing a quota, the plans window, and accepting an Apple in-app purchase as proof of entitlement. Prerequisites: an auth provider configured with cycls.Web().auth(...), and a volume at /workspace.

Read the plan

context.user.plan is whatever your identity provider puts in the JWT claim. The Cycls-hosted Clerk application emits:
{"type": "ui", "action": "open_plan_modal"} opens the plans window. The client selects user plans or organization plans based on the active organization.

Meter usage per user

Store the counter in cycls.DB, which writes to the /workspace volume. Keying by month means history accumulates and resets happen without a scheduled job. Report the count to the chat with a usage event on every reply of a limited plan.
Expected behavior: from a free user’s 11th message in a month, a line above the composer counts what is left. The 14th is answered, and the plans window opens as that reply ends, once that month on each device. The 15th gets a note in place of a reply that thanks the person by the agent’s name and offers the plans, and the model is never called. The mobile app shows its own alert.
cycls.DB writes are atomic per key, not transactional across keys. Two requests racing on the same counter can both read the same value. For strict enforcement, check the counter again after incrementing, or accept a small overshoot.

The plans window

The plans window shows your Clerk plans. One button leads, for the plan on offer, already chosen: the first paid plan the person does not have. Under it come the price, a local amount and “cancel anytime”, then the ways to pay, the choice of plan and billing period with the yearly saving, and the plan’s features. Opened by a limit, it thanks the person first. Not now closes it.

Track spend

Set token prices so every turn logs its cost:
Prices are USD per million tokens. Query the result with cycls cost and cycls sql. Without .price(), costs are logged as zero.

Apple in-app purchase

Use this when an iOS client sells the subscription and the agent has to trust it without calling Apple on every request.
How verification works: the iOS client sends its current StoreKit 2 signed transaction in the header. Cycls validates the certificate chain against the bundled Apple Root CA G3, checks the product and expiry, and confirms that the purchase’s appAccountToken derives from the authenticated user id under your namespace. A valid entitlement raises user.plan for that request only. The appAccountToken binding is what stops a valid receipt from one account being replayed by another. Both client and server must derive it with the same UUIDv5 namespace.

Affiliate tracking

The key is injected into the page config. The client loads the tracker and reports conversions at checkout.

Next

Local and remote builds

Where a build happens, and which code it contains.