Storefront Guides
Subscriptions
The Subscriptions module allows you to offer products and services on a recurring basis, enabling business models like “Subscribe & Save,” SaaS, content access, and custom refill schedules. Commerce Engine provides APIs to define subscription plans on products, let users initiate subscriptions, and manage the lifecycle of those subscriptions.
Key Distinction
Subscriptions are initiated and managed separately from the standard one-time purchase checkout flow (POST /orders). Creating a subscription typically involves the POST /subscriptions endpoint and a subsequent mandate/payment step, bypassing the standard cart-to-order conversion for the subscription itself.
Prerequisites
- Payment Gateway: Juspay integration is required for managing recurring payment mandates.
- Product Configuration: Products intended for subscription must have plans defined in the
subscriptionarray within their Catalog data.
Key Features:
- Standard & Custom Plans
- Billing & Shipping Cycles
- Trial Periods (Digital)
- Lifecycle Management (Create, View, Update, Pause, Revoke via API)
- Coupon Integration (Applied during
POST /subscriptions) - (Usage-Based Billing - Future)
Core Concepts
Understanding Subscription Data
Understanding Subscription Data
These schemas define the structure of subscription data you’ll work with when listing, viewing, or managing subscriptions.
The Subscription Object
The Subscription Object
This object is typically returned in lists (GET /subscriptions) and provides a summary view.
id(string, readOnly): Unique identifier for the subscription.plan_id(string, readOnly): Identifier of the base plan from the catalog (if standard).plan_name(string, readOnly): Name of the subscription plan.price(number): The base recurring price for the subscription period.status(enum, readOnly): Current state:created,active,paused,revoked.start_date(string, format: date): The date the subscription officially began or will begin.end_date(string | null, format: date): The date the subscription is set to automatically revoke (if specified).trial_days(integer): Number of free trial days (primarily for digital).trial_start_date(string | null, format: date, readOnly): Start date of the trial period.trial_end_date(string | null, format: date, readOnly): End date of the trial period.next_billing_date(string, format: date, readOnly): Date the next invoice/charge is scheduled.last_payment_date(string | null, format: date-time, readOnly): Timestamp of the last successful payment.pause_start_date(string | null, format: date): If paused, when the pause period started or will start.pause_end_date(string | null, format: date): If paused, when the subscription is scheduled to automatically resume. Null means indefinite pause.- Scheduling:
billing_frequency(enum): How often billing occurs (e.g.,monthly).billing_interval(integer): Multiplier for frequency (e.g.,1for every month,2for every 2 months).billing_limit(integer | null): Total number of billing cycles allowed (null for indefinite).shipping_frequency(enum): How often shipping occurs (physical products).shipping_interval(integer): Multiplier for shipping frequency.shipping_limit(integer | null): Total number of shipments allowed (null for indefinite).
- Coupons:
coupon_id(string | null): ID of the applied coupon.coupon_code(string | null): Code of the applied coupon.coupon_discount_percent(number): Percentage discount from coupon.coupon_discount_amount(number): Fixed amount discount from coupon.coupon_redemption_limit(integer | null): How many cycles the coupon applies for (null for duration of subscription).
- Behavior:
is_prepaid(boolean): Is the subscription paid fully upfront?usage_based_billing(boolean): Is billing based on usage (digital)? (Currently not supported for initiation but placeholder exists).usage_based_tiers(array): Pricing tiers for usage-based billing. (Currently not supported for initiation).grace_period_days(integer): Days allowed for payment retry after failure.
- Cancellation Rules:
is_cancellation_allowed(boolean): Can the customer currently initiate cancellation?days_until_cancellation_allowed(integer): How many days before the next billing date cancellation must be done.
currency(Currencyobject): Details of the subscription currency.metadata(object): Custom key-value pairs.created_at(string, format: date-time, readOnly): Timestamp of creation.modified_at(string, format: date-time, readOnly): Timestamp of last modification.
SubscriptionDetail Schema
SubscriptionDetail Schema
Returned by GET /subscriptions/{id} and POST /subscriptions, includes everything in the Subscription schema plus:
invoice_items(array ofSubscriptionInvoiceItem): Details of the specific products/variants included in this subscription.billing_address(CustomerAddressobject | null): The billing address associated with the subscription.shipping_address(CustomerAddressobject | null): The shipping address (for physical products).
SubscriptionInvoiceItem Schema
SubscriptionInvoiceItem Schema
Details about each product/variant within a subscription.
product_id(string): ID of the included product.variant_id(string | null): ID of the included variant (if applicable).product_name(string, readOnly): Name of the product.variant_name(string, readOnly): Name of the variant.product_image_url(string, readOnly): Image URL.sku(string, readOnly): SKU of the item.quantity(integer): Quantity of this item included per cycle.listing_price(number, readOnly): Original price per unit.selling_price(number, readOnly): Subscription price per unit for this item.tax_type(string, readOnly): Type of tax (e.g., “GST”).tax_rate(number, readOnly): Tax rate percentage.price_including_tax(boolean, readOnly): Was the selling price entered inclusive of tax?selling_price_excluding_tax(number, readOnly): Calculated selling price before tax.
Schemas for Creating/Updating (POST/PUT /subscriptions)
Schemas for Creating/Updating (POST/PUT /subscriptions)
These define the structure of the request body when creating or updating subscriptions.
CreateStandardSubscription: Used when initiating a subscription based on a pre-defined plan from the product catalog.plan_type: Must be"standard".plan_id: Required. The ID of theProductSubscriptionplan selected from the product.start_date: (Optional) Defaults to current date if omitted.end_date: (Optional) Date to automatically revoke.coupon_code: (Optional).
CreateCustomSubscription: Used when creating a subscription with a custom schedule (often for multi-item subscriptions).plan_type: Must be"custom".start_date: (Optional).end_date: (Optional).billing_frequency: Required. e.g.,"monthly".billing_interval: Required. e.g.,1.billing_limit: (Optional).shipping_frequency: (Optional, for physical).shipping_interval: (Optional, for physical).shipping_limit: (Optional, for physical).coupon_code: (Optional).
SubscriptionBehaviour: Defines billing rules, often included alongside Create/Update schemas.is_prepaid: (Optional, defaultfalse).grace_period_days: (Optional, default0).is_cancellation_allowed: (Optional, defaulttrue).days_until_cancellation_allowed: (Optional, default3).- (Usage-based fields omitted as not currently supported for initiation)
UpdatePhysicalProductSubscription/UpdateDigitalProductSubscription: Used withcommand: "update"inPUT /subscriptions/{id}. Allows changing schedule fields (billing_frequency, etc.), behavior fields (grace_period_days, etc.), and potentiallyinvoice_items(subject to mandate rules).PauseSubscription: Used withcommand: "pause"inPUT /subscriptions/{id}.command: Must be"pause".pause_start_date: (Optional) Schedule pause start.pause_end_date: (Optional) Schedule automatic resume.
RevokeSubscription: Used withcommand: "revoke"inPUT /subscriptions/{id}.command: Must be"revoke".reason: Required. Text reason for cancellation.
Subscription Initiation Flows
There are two primary ways a user initiates a subscription:
Flow 1: Standard Single-Product Subscription ('Subscribe & Save')
Flow 1: Standard Single-Product Subscription ('Subscribe & Save')
- Discovery: User browses a Product Detail Page (PDP). The
subscriptionarray within theProduct/Variantdata shows available plans (e.g., “Monthly Delivery - Save 10%”). - Selection: User selects a specific
ProductSubscriptionplan ID and quantity. - Initiation: User clicks a “Subscribe Now” (or similar) button.
- Data Collection (Frontend): Your application collects necessary details not already available:
- Billing Address
- Shipping Address (if physical product)
- User details (if anonymous and needs registration)
- API Call: Your application calls
POST /subscriptions.- Body: Includes
plan_type: "standard", the selectedplan_idfrom the product, theinvoice_itemsarray (containing just this one product/variant and quantity), user details, addresses, and potentially acoupon_code.
- Body: Includes
- Mandate/Payment Step (Conceptual): The successful response from
POST /subscriptions(or a related, subsequent call - API endpoint TBC) will provide details (like a Juspay redirect URL or SDK payload) to:- Collect initial payment (if applicable, e.g., not a free trial).
- Obtain user authorization for the recurring payment mandate via Juspay.
- Activation: Upon successful payment/mandate authorization, Commerce Engine activates the subscription (status becomes
active).
Standard Single-Product Subscription Flow Diagram
Standard Single-Product Subscription Flow
Flow 2: Custom Multi-Product Subscription (Advanced)
Flow 2: Custom Multi-Product Subscription (Advanced)
- Discovery & Cart Building: User adds multiple subscription-eligible products/variants to the standard cart (
POST /carts,POST /carts/{id}/items). The frontend must track which items are intended for subscription. - Subscription Checkout Trigger: User proceeds to a checkout flow specifically designated for creating a custom subscription from the cart contents (distinct from the one-time purchase checkout).
- Schedule Selection: Your application prompts the user to select one common billing frequency and interval for all items being subscribed to in this batch. Shipping frequency might also be unified or handled based on item defaults.
- Data Collection (Frontend): Confirm/collect billing and shipping addresses.
- API Call: Your application calls
POST /subscriptions.- Body: Includes
plan_type: "custom", the selectedbilling_frequency,billing_interval,billing_limit, theinvoice_itemsarray (listing all products/variants from the cart intended for this subscription), user details, addresses, and potentially acoupon_code.
- Body: Includes
- Mandate/Payment Step (Conceptual): Similar to Flow 1, trigger the Juspay mandate/payment process based on the API response. The mandate
maxAmountshould cover the combined cost of all items in the custom subscription bundle. - Activation: Upon success, Commerce Engine activates the single custom subscription covering all included items.
Custom Multi-Product Subscription Flow Diagram
Custom Multi-Product Subscription Flow
Subscription API Endpoints
POST /subscriptions
POST /subscriptions
Primary endpoint for initiating both standard (single-item) and custom (multi-item) subscriptions. This call gathers all necessary subscription details before triggering the payment/mandate process.
- Authentication: Bearer Token (Typically Logged-in, but anonymous might be possible if registration occurs implicitly during mandate/payment).
- Request Body: Combines:
- Plan Details:
CreateStandardSubscription(usingplan_idfrom product) ORCreateCustomSubscription(defining schedule). - Items:
invoice_itemsarray (one item for standard, multiple for custom). - Behavior:
SubscriptionBehaviour(prepaid, grace period etc.). - User Context: Implicitly via token, but might need explicit user details if creating for anonymous user needing registration.
- Addresses: Billing and Shipping address objects.
coupon_code: (Optional).
- Plan Details:
- Response:
200 OKcontaining the newly createdSubscriptionDetailobject (likely withstatus: 'created').The mechanism for providing payment/mandate details (e.g., Juspay URL/payload) in the response or via a subsequent call is To Be Confirmed (TBC).
GET /subscriptions
GET /subscriptions
Retrieves a list of the customer’s subscriptions (active, paused, past) for display in “My Account”.
- Authentication: Bearer Token (Logged-in user)
- Response: Paginated list of
Subscriptionsummary objects.
GET /subscriptions/{id}
GET /subscriptions/{id}
Fetches complete details (SubscriptionDetail object) for managing a specific subscription.
- Authentication: Bearer Token (User must own the subscription)
- Path Parameter:
id(Subscription ID) - Response:
SubscriptionDetailobject.
PUT /subscriptions/{id}
PUT /subscriptions/{id}
Manage the lifecycle and configuration of an existing subscription (pause, revoke, update schedule/items - subject to mandate rules).
- Authentication: Bearer Token (User must own the subscription)
- Path Parameter:
id(Subscription ID) - Request Body: Uses
command: "update",command: "pause", orcommand: "revoke"with relevant schema (Update...Subscription,PauseSubscription,RevokeSubscription). - Response: Updated
SubscriptionDetailobject.