1---2name: kibo-subscriptions3description: Use for Kibo Subscription Commerce work — implementing recurring billing, configuring plans (evergreen, fixed-term, subscribe-and-save), managing subscriptions (pause, skip, swap, cancel), setting up dunning / retry for failed payments, handling cycles and continuity orders, building customer self-service portals, and understanding the Subscription-to-Order relationship. Triggers on Kibo Subscription, Kibo Subscription Commerce, subscriptionCreate, subscriptionUpdate, subscription cycle, subscription pause / skip / swap, subscription dunning, recurring billing Kibo, evergreen subscription, fixed-term subscription, subscribe and save, continuity order, payment recycling, subscription churn, subscription retention. Invoke for any Kibo Subscription question — API integration, implementation, configuration, debugging, or projecting subscription state into reporting/ERP.4---56# Kibo Commerce — Subscriptions78**Progressive loading — only load what you need:**910- Setting up auth, the SDK, the tenant model (shared with all Kibo products)? Load [references/api-setup.md](references/api-setup.md)11- Modeling Subscriptions, plans, the entity lifecycle, the relationship to Orders? Load [references/subscription-model.md](references/subscription-model.md)12- Configuring plans, frequencies, trials, fixed-term vs evergreen? Load [references/plans.md](references/plans.md)13- Implementing billing cycles, dunning, retry, notifications? Load [references/billing-dunning.md](references/billing-dunning.md)14- Handling modifications (skip, swap, change frequency, change address)? Load [references/modifications.md](references/modifications.md)15- Designing cancellation, pause, and retention flows? Load [references/retention.md](references/retention.md)16- Reviewing or debugging existing code? Load [references/anti-patterns.md](references/anti-patterns.md)1718**Load the relevant reference file before writing Kibo Subscriptions integration code.** Subscriptions look like "orders that repeat" until you have to handle a paused subscription with a swapped SKU and a deferred charge — at which point the differences matter. The Subscription entity has its own lifecycle, its own state transitions, and its own relationship to Orders (each cycle typically creates a new Order rather than amending one).1920## CRITICAL Priority2122| Pattern | File | Impact |23|---------|------|--------|24| Tenant / site model and `x-vol-*` headers (shared with all Kibo products) | [references/api-setup.md](references/api-setup.md) | Wrong header → wrong scope |25| A Subscription is not an Order — each cycle creates a new Order | [references/subscription-model.md](references/subscription-model.md) | Code that mutates the original Order across cycles breaks reporting and refunds |26| Subscription lifecycle (`Pending`, `Active`, `Paused`, `Errored`, `Failed`, `Cancelled`) is distinct from Order lifecycle; `Errored` ≠ `Failed` (Errored can auto-recover via recycling, Failed is recycling-exhausted) | [references/subscription-model.md](references/subscription-model.md) | Treating "subscription failed" the same as "order failed" produces stuck states and wrong dunning |27| Dunning is a configurable retry schedule, not a retry-on-failure loop | [references/billing-dunning.md](references/billing-dunning.md) | Ad-hoc retry loops bypass dunning rules and over-charge or under-collect |2829## HIGH Priority3031| Pattern | File | Impact |32|---------|------|--------|33| Stored payment methods + off-session SCA / 3DS for recurring charges | [references/billing-dunning.md](references/billing-dunning.md) | Off-session charges that don't handle SCA fail silently in EU markets |34| Modifications: skip vs swap vs change-frequency are different mutations | [references/modifications.md](references/modifications.md) | Conflating them produces wrong proration |35| Pause is a retention tool, not a cancel — has different reactivation semantics | [references/retention.md](references/retention.md) | Cancelling instead of pausing loses customer LTV signal |36| Cancellation is terminal and immediate — there is no `cancelAtPeriodEnd` flag; end-of-period semantics must be built explicitly (skip-then-cancel or pause-then-cancel) | [references/retention.md](references/retention.md) | Code that assumes Stripe-style `cancel_at_period_end` is configurable surprises customers and triggers chargebacks |37| Plan attribute changes vs subscription attribute changes apply at different scopes | [references/plans.md](references/plans.md) | Editing the plan affects all subscribers; editing the subscription affects one |3839## MEDIUM Priority4041| Pattern | File | Impact |42|---------|------|--------|43| Trial periods affect first charge timing | [references/billing-dunning.md](references/billing-dunning.md) | Off-by-one trial computation creates wrong charge dates |44| Frequency expressed as interval + unit (weekly, monthly, every-N) | [references/plans.md](references/plans.md) | Custom cadences need the interval form, not predefined enums |45| Bundle subscriptions (multiple SKUs in one cycle) have their own line semantics | [references/subscription-model.md](references/subscription-model.md) | Treating a bundle as a single SKU loses per-line fulfillment status |46| Address change on active subscription: applies next cycle, not the current one | [references/modifications.md](references/modifications.md) | Mid-cycle address changes are ambiguous; document the policy |4748## Common Anti-Patterns (Quick Reference)4950| Anti-Pattern | File | Consequence |51|--------------|------|-------------|52| Building dunning as a custom retry loop | [references/anti-patterns.md](references/anti-patterns.md) | Bypasses platform-configured retry rules; produces wrong customer notifications |53| Treating each cycle's Order as an amendment to the prior Order | [references/anti-patterns.md](references/anti-patterns.md) | Each cycle is its own Order with its own state |54| Hardcoded next-charge-date computation | [references/anti-patterns.md](references/anti-patterns.md) | Leap years, paused cycles, swapped plans break the math |55| Off-session charges without SCA / 3DS handling | [references/anti-patterns.md](references/anti-patterns.md) | Silent failures in EU markets |56| Cancellation = immediate by default | [references/anti-patterns.md](references/anti-patterns.md) | Customer expects access through end of period; chargebacks follow |57| Pause modelled as a temporary cancel | [references/anti-patterns.md](references/anti-patterns.md) | Loses retention signal and forces full re-onboarding |5859## Live Documentation as Source of Truth6061| Need | Source |62|------|--------|63| Subscription product page | [kibocommerce.com/platform/subscription](https://kibocommerce.com/platform/subscription/) |64| Concept and developer guides | [docs.kibocommerce.com](https://docs.kibocommerce.com/) |65| Interactive API reference | [apidocs.kibocommerce.com](https://apidocs.kibocommerce.com/) |66| Hosted MCP server for runtime API access | [docs.kibocommerce.com/pages/kibo-mcp-server](https://docs.kibocommerce.com/pages/kibo-mcp-server) |6768**Workflow:** Use this skill to understand the right pattern → use apidocs.kibocommerce.com to look up exact field names → use Kibo's hosted MCP server to test the call against a real tenant.6970## Related Skills7172- [kibo-ecommerce](../kibo-ecommerce/SKILL.md) — when products are subscribable and the catalog/cart layer is also Kibo73- [kibo-oms](../kibo-oms/SKILL.md) — subscription cycle orders flow through OMS for fulfillment like regular orders74- [commercetools-api](../commercetools-api/SKILL.md) — for clients running Kibo Subscriptions behind commercetools as the storefront/checkout
ariessolutionsio