Plans and reliability
Subscriptions and entitlements
Learn which Developer Platform capabilities and limits are controlled by the account subscription.
What this guide covers
- One account subscription governs access across its Agent Projects.
- Entitlements can limit keys, webhook endpoints, retention, and throughput.
- An active subscription does not imply that Yanola Balance is available.
What the Yanola Subscription controls
The Yanola Subscription is an account-level access contract for the Developer Platform. Active or trialing status plus a valid plan allows entitled operations across the account's Agent Projects. It is separate from the prepaid Yanola Balance, which pays for SaaS usage.
| Layer | Decision |
|---|---|
Subscription status | Whether Developer Platform access is currently allowed. |
Plan configuration | Which entitlement values apply to the account. |
Entitlement usage | Whether the requested Agent Project, key, endpoint, environment, or operation fits within those values. |
Yanola Balance | Whether SaaS usage such as a workflow or a scheduled send can be paid. API and SDK sends do not use it. |
Subscription status and recovery
Treat the dashboard's access result as authoritative. Stripe lifecycle events update the account subscription, and Yanola maps the stored status to a specific recovery action.
| Status | Developer Platform access | Recovery action |
|---|---|---|
active / trialing | Allowed when the referenced plan configuration is available. | No action. |
incomplete | Blocked while checkout is unfinished. | Complete the existing checkout. |
past_due / unpaid | Blocked because subscription payment needs attention. | Update the payment method in the billing portal. |
paused | Blocked while the subscription is paused. | Resume or manage the subscription in the billing portal. |
none / canceled / incomplete_expired | Blocked because no usable subscription is present. | Start a subscription from account Billing. |
active / trialing with missing plan configuration | Blocked to avoid granting undefined access. | Manage the subscription or contact support. |
Developer Platform entitlements
Entitlement values come from the account's current plan and are shown in Billing. That current account view is the stable public discovery contract. Do not hard-code plan names, prices, seed tiers, or limit quantities into your integration because commercial offers can change without changing REST /v1.
| Entitlement | What it controls |
|---|---|
api_enabled_agent_projects | How many Agent Projects can use Developer Platform capabilities under the account. |
api_keys_per_agent_project | Maximum active API keys for each enabled Agent Project. |
webhook_endpoints_per_agent_project | Maximum webhook endpoint configurations for each enabled Agent Project. |
rate_limit_tier | The account's API throughput tier; use response rate-limit headers for live capacity. |
log_retention_days | How long normalized Developer Platform logs remain available. |
test_mode_enabled | Whether Test Mode operations are included. |
support_level | The support level associated with the plan. |
When there is no usable plan, numeric limits are zero, Test Mode is disabled, and tier/support values are none.
How limits are enforced
Yanola checks access before enabling an Agent Project or performing an entitled operation. Existing active API keys count toward the per-project key limit, and configured webhook endpoints count toward the per-project endpoint limit.
| Error code | HTTP status | When it occurs | Action |
|---|---|---|---|
subscription_required | 403 | No active or trialing subscription grants access. | Start a subscription. |
subscription_incomplete | 403 | Subscription checkout has not completed. | Resume the existing checkout. |
subscription_past_due | 403 | The subscription is past due or unpaid. | Update the payment method. |
subscription_inactive | 403 | The subscription is paused or its active plan configuration is unavailable. | Manage the subscription or contact support. |
test_mode_not_included | 403 | The plan does not include Test Mode. | Change plan or use an entitled environment. |
agent_project_limit_reached | 403 | Enabling another Agent Project would exceed the account limit. An unlimited plan never returns this code. | Disable unused access or change plan. |
api_key_limit_reached | 403 | Creating another active key would exceed the project limit. An unlimited plan never returns this code. | Revoke an unused key or change plan. |
webhook_endpoint_limit_reached | 403 | Creating another endpoint would exceed the project limit. An unlimited plan never returns this code. | Remove an unused endpoint or change plan. |
plan_message_limit_reached | 402 | Monthly Message Cap reached (not retryable). | wait for the next period or upgrade the Plan; replies inside the 24-hour window, free-form or template, still go out. |
Entitlement failures use 403 permission_error behavior. Adding Yanola Balance does not resolve them.
Start or complete a subscription
Use the Yanola Subscription card on the account Billing page. Choose a public purchasable plan to open Stripe Checkout. If an unexpired checkout already exists for the same plan, Yanola resumes that session instead of creating a duplicate.
- Review the current plan's entitlement values in Billing.
- Choose the plan and complete Stripe Checkout.
- Return to Billing and wait for the subscription status to become active or trialing.
- If checkout remains incomplete, use Complete checkout rather than starting repeated sessions.
- Create or enable Agent Project resources only after access is allowed.
Returning from Stripe is not itself proof of access. Yanola applies Stripe subscription events idempotently and ignores duplicate or stale updates.
Manage payment and lifecycle changes
Accounts with an existing Stripe customer and a managed subscription state use the billing portal to update payment details, resume service, or change cancellation settings. Yanola does not create a second checkout while the current subscription must be managed.
A cancel-at-period-end setting is distinct from immediate loss of access: use the current subscription status, access.allowed result, and current period end shown in Billing. Access stops when the synchronized state no longer allows it.
| Dashboard action | Use it for |
|---|---|
Choose plan | Starting a new subscription when the account has no managed subscription. |
Complete checkout | Resuming the stored, unexpired incomplete checkout. |
Manage subscription | Updating payment details, recovering past-due or paused access, and managing cancellation. |
Contact support | A selected plan lacks checkout configuration or an active subscription references unavailable plan configuration. |
Account scope and Agent Projects
One subscription governs Developer Platform access for the Yanola Account; individual Agent Projects do not buy separate subscriptions. The account-level api_enabled_agent_projects entitlement limits how many projects can be enabled, while key and webhook limits apply separately within each enabled project.
Yanola records entitlement enablement and subscription lifecycle changes in the account audit trail. Keep project ownership and least-privilege API key scopes in place even when a plan permits higher limits.
Combine Subscription and Balance checks
For Live Mode API readiness, verify the subscription and the Message Cap. Subscription access answers whether the account may use the capability; the Message Cap answers whether another send fits in this period. Yanola Balance only matters for SaaS usage.
- Confirm subscription status is active or trialing and access is allowed.
- Confirm the plan includes the required environment and the resource is within its entitlement limit.
- Confirm the API key has the necessary scope and Sender restriction.
- Confirm the account is under its monthly Message Cap for new API and SDK sends.
- After acceptance, monitor message delivery to its final state.
| Subscription | Balance | Result |
|---|---|---|
Allowed | Sufficient | Entitled API sends and Balance-funded SaaS usage can proceed. |
Allowed | Insufficient | API sends within the Message Cap, reads, and configuration remain available; Balance-funded activity is blocked, and a public API action billed from the Balance returns 402 insufficient_balance. |
Blocked | Funded | Developer Platform access remains blocked; a top-up does not repair the subscription. SaaS usage stays available. |
Blocked | Depleted | Resolve subscription access for the API, and fund Balance for SaaS usage. |
Operational ownership
Subscription and Balance management are dashboard account-owner workflows, not public /v1 SDK operations. Server applications should handle stable public permission and billing errors without embedding Stripe credentials, plan identifiers, or account payment logic.
- Alert account owners on subscription_past_due, subscription_inactive, low Balance, and failed auto top-up states.
- Direct subscription recovery to account Billing and the Stripe billing portal.
- Direct insufficient_balance recovery to a Balance top-up.
- Use usage records and request IDs for spend investigation; use Billing for invoices and payment state.