Developer Reference
See the Subscription API documentation for programmatic access
Watch: Subscription Configuration
Learn how to configure subscription attributes and create offline subscription orders
Watch: Subscription Site Settings
See how to configure subscription settings at the site level
Looking for webhook configurations? See Event Subscription for information about subscribing applications to Kibo platform events.
1. Strategic Overview
Concept Definition: Subscriptions enable automated recurring purchases through recurring orders, transforming one-time transactions into predictable, long-term customer relationships. Business Context: Kibo Commerce subscriptions serve as a foundational revenue optimization capability within the unified commerce platform. It is designed to manage the complete subscription lifecycle, from initial creation through ongoing payment processing and customer communications, by providing a dual management approach. Firstly, it offers comprehensive automation for recurring orders, payments, and standard communications, driving predictable revenue and operational efficiency. Secondly, the platform provides flexible direct management capabilities that allow users to intervene, modify, and manage subscriptions for necessary operational adjustments, personalized service and resolution of complex customer scenarios. Value Drivers:- Predictable Revenue Streams: Automated recurring orders create consistent, forecastable income that supports strategic planning and improves financial stability through recurring customer commitments, enabling more confident business investments and enhanced cash flow predictability.
- Operational Automation Excellence: Comprehensive automation of order generation, payment processing, inventory allocation, and customer communications eliminates manual intervention while reducing operational costs and human error across the entire subscription lifecycle.
- Enhanced Customer Lifetime Value: Long-term recurring relationships foster deeper customer engagement, provide extensive behavioral data for personalization, and create multiple touchpoints for additional value delivery and strategic cross-selling opportunities.
2. Core Concepts Explained
What is Subscription?
Subscriptions in Kibo Commerce represent a comprehensive recurring commerce solution that automates repeat purchases—transactions generated at predefined intervals based on customer-selected frequencies and configured business rules.The system transforms traditional one-time purchases into ongoing customer relationships by handling the complete subscription lifecycle: from initial setup and trial periods through recurring order generation, payment processing, fulfillment coordination, and lifecycle management.Why does Subscriptions matter?
Subscriptions are the core functional mechanism through which Kibo Commerce enables predictable revenue streams and operational automation. The platform’s comprehensive capabilities automates the transition from single purchases to long-term customer relationships. Kibo Commerce enables this through unified capabilities, including sophisticated payment recycling and installment options, providing customers with flexibility to choose between one-time purchases and recurring commitments, and flexible management features, ensuring scalability and fine-grained operational control over every recurring revenue stream.When to deploy Subscriptions?
Business Triggers: Deploy subscriptions for products with regular consumption patterns, curated collections requiring periodic delivery, services with ongoing access requirements, or high-value items benefiting from installment payment options. The system supports both B2C consumable replenishment and B2B bulk ordering scenarios, enabling diverse business models under unified subscription management while accommodating international expansion and complex operational requirements. Maturity Requirements: Subscription deployment requires established product catalogs, configured payment gateways supporting recurring transactions, defined customer account structures. Timeline to Value: The strategic decision to deploy is justified by a dual-phased value realization. Immediate Value begins upon the first subscription creation, as automated recurring orders instantly generate forecastable recurring revenue from the first billing cycle. Long-Term Value is realized through the adoption and configuration of advanced platform features, such as payment recycling and installment plans, which systematically enhance customer retention, reduce involuntary churn, and improve operational efficiency over time. This phased value realization supports both quick ROI and sustained growth across the entire customer base.3. Functional Components & Configuration Deep Dive
3.1 Component Architecture
The subscription system operates through a structured hierarchy of interconnected business components:Subscription Component
Functionality: Handles recurring order creation based on customer-selected frequencies, business rules, and operational timing controls Business Purpose: Enables predictable revenue streams and reduces manual order processing overhead while supporting complex scheduling requirementsProduct Configuration Component
Functionality: Defines subscription eligibility, frequency options, trial capabilities, and bundle configurations at product portfolio levels Business Purpose: Enables scalable subscription rollouts and consistent customer experience across product lines while supporting diverse business modelsSubscription Lifecycle Management
Functionality: Provides pause, skip, modification, and cancellation capabilities for both customers and service representatives with configurable automation policies Business Purpose: Reduces churn through flexibility while maintaining customer relationships during changing needs and circumstances Subscription Status Definitions: The subscription lifecycle is managed through distinct status states that control system behavior and enable appropriate customer service and reporting capabilities:- Pending: Subscriptions that have been created but not yet activated
- Active: Subscriptions that are active and generating recurring orders according to their configured frequency and business rules
- Paused: Subscriptions temporarily suspended by customer or administrative action, with automatic or manual reactivation capabilities
- Errored: Subscriptions where a problem occurred during processing, typically related to payment issues preventing the subscription from functioning normally. Resolution requires addressing the underlying issue to restore subscription operation
- Failed: Subscriptions where the system attempted multiple times to generate recurring orders but was unsuccessful, causing automatic order creation to stop. Manual intervention or successful order placement can restore normal subscription functionality
- Cancelled: Subscriptions permanently terminated by customer or administrative action, with no further recurring orders generated

Subscription Pricing System
Functionality: Manages subscription-specific pricing, price locking mechanisms, promotional pricing structures, and installment payment options Business Purpose: Enables competitive subscription value propositions while protecting customer trust through price consistency and payment flexibilityTrial and Conversion System
Functionality: Handles trial product substitution, duration management, automated conversion to full subscriptions, and conversion optimization tracking Business Purpose: Reduces customer acquisition barriers and enables product demonstration before commitment while optimizing conversion ratesCommunication and Notification System
Functionality: Manages proactive customer communications for status changes, upcoming orders, and required actions. Business Purpose: Reduces support burden while improving customer satisfaction through transparent communication and automated workflow integration3.2 Business Configuration Deep Dive
This consolidated table highlights the most important, high-level settings that determine what subscription is offered and how the system operationally manages the recurring revenue stream.| Configuration Name | Business Purpose | Impact and Trade-offs | Concrete Example |
|---|---|---|---|
| Subscription Mode | Defines the fundamental purchasing commitment (one-time, mixed, or subscription-only). | Directly impacts customer acquisition strategy; balances maximum recurring revenue potential against offering customer flexibility. | A premium roaster sets artisanal blends to Subscription-Only to secure consistent monthly revenue. |
| Subscription Frequency | Aligns automated delivery schedules with customer consumption patterns by offering pre-configured and custom frequencies. | Balances customer satisfaction (offering variety) against operational complexity (inventory and fulfillment planning). | A pet company offers Monthly and Bi-Monthly frequencies to match consumption rates for different dog sizes. |
| Trial Days | Reduces commitment barriers by enabling a limited-time product experience before full commitment. | Longer trials may delay revenue but increase acquisition potential; requires clear communication on the transition date. | A meal kit service offers a 7-day trial to demonstrate quality before transitioning to the full subscription. |
| Trial Product Code / Variation Code | Effective trial products must demonstrate value while remaining cost-effective for customer acquisition and competitive with market alternatives. | Enables a precise, cost-effective trial experience optimized for value demonstration and high conversion potential. | A skincare brand uses sample-sized starter kits to control fulfillment costs. |
| Order Scheduling Controls | Governs the timing of order creation (Create Continuity Order X Days Before Next Order Date), order date reset rules (Order Now Resets Next Order Date), and the limit for manually delaying the next order (Update Next Order Date Up to X Days) | Important for controlling fulfillment lead times, improving inventory allocation, and governing customer/admin control over the delivery schedule. | The system creates the order 7 days early for fulfillment planning. Ordering early via the Order Now action automatically resets the subsequent delivery schedule. |
| Skip / Pause Controls | Limits the number of consecutive orders a customer can skip and the total duration a subscription can remain paused before auto-reactivation. These are controlled by settings like Skip Subscription X Times and Pause Subscription Duration Limits. | Balances providing customer flexibility during temporary needs changes against the strategic goal of long-term revenue retention. | A customer can skip 2 orders. A paused subscription will auto-reactivate after three missed orders. |
| On-Demand Ordering Controls | Sets a restriction period (Allow Order All or Partial Items Now Once Every X Days) after an on-demand “Order All/Partial Items Now” action is performed. | Ensures appropriate timing between urgent fulfillment requests, maintaining overall subscription schedule integrity. | On-demand ordering is restricted for 30 days after a partial order is placed early. |
| Communication & Notification Strategy | Manages timing, frequency, and triggers for all automated customer emails (reminders, status, modifications, reactivations). | Enables proactive customer relationship management by providing important advance notice before the recurring order is created, setting expectations during lifecycle changes, and informing customers of account status and modifications | An email is sent 3 days before an order processes, and a separate notification confirms the Subscription Status Change. |
| Subscription Attribute Scope Settings | Defines if custom data fields apply only to the subscription relationship, or to both the subscription and individual recurring orders. | Enables the capture of unique data (e.g., compliance or project codes) that supports operational reporting, downstream fulfillment requirements, and financial reconciliation across the subscription lifecycle. | A B2B client captures the “Department Budget Code” attribute, scoped to persist across all recurring orders |

