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.
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.subscription
array within their Catalog data.POST /subscriptions
)Understanding Subscription Data
The Subscription Object
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.billing_frequency
(enum): How often billing occurs (e.g., monthly
).billing_interval
(integer): Multiplier for frequency (e.g., 1
for every month, 2
for 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).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).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.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
(Currency
object): 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
GET /subscriptions/{id}
and POST /subscriptions
, includes everything in the Subscription
schema plus:invoice_items
(array of SubscriptionInvoiceItem
): Details of the specific products/variants included in this subscription.billing_address
(CustomerAddress
object | null): The billing address associated with the subscription.shipping_address
(CustomerAddress
object | null): The shipping address (for physical products).SubscriptionInvoiceItem Schema
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)
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 the ProductSubscription
plan 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, default false
).grace_period_days
: (Optional, default 0
).is_cancellation_allowed
: (Optional, default true
).days_until_cancellation_allowed
: (Optional, default 3
).UpdatePhysicalProductSubscription
/ UpdateDigitalProductSubscription
: Used with command: "update"
in PUT /subscriptions/{id}
. Allows changing schedule fields (billing_frequency
, etc.), behavior fields (grace_period_days
, etc.), and potentially invoice_items
(subject to mandate rules).PauseSubscription
: Used with command: "pause"
in PUT /subscriptions/{id}
.
command
: Must be "pause"
.pause_start_date
: (Optional) Schedule pause start.pause_end_date
: (Optional) Schedule automatic resume.RevokeSubscription
: Used with command: "revoke"
in PUT /subscriptions/{id}
.
command
: Must be "revoke"
.reason
: Required. Text reason for cancellation.Flow 1: Standard Single-Product Subscription ('Subscribe & Save')
subscription
array within the Product
/Variant
data shows available plans (e.g., โMonthly Delivery - Save 10%โ).ProductSubscription
plan ID and quantity.POST /subscriptions
.
plan_type: "standard"
, the selected plan_id
from the product, the invoice_items
array (containing just this one product/variant and quantity), user details, addresses, and potentially a coupon_code
.POST /subscriptions
(or a related, subsequent call - API endpoint TBC) will provide details (like a Juspay redirect URL or SDK payload) to:
active
).Standard Single-Product Subscription Flow
Flow 2: Custom Multi-Product Subscription (Advanced)
POST /carts
, POST /carts/{id}/items
). The frontend must track which items are intended for subscription.POST /subscriptions
.
plan_type: "custom"
, the selected billing_frequency
, billing_interval
, billing_limit
, the invoice_items
array (listing all products/variants from the cart intended for this subscription), user details, addresses, and potentially a coupon_code
.maxAmount
should cover the combined cost of all items in the custom subscription bundle.Custom Multi-Product Subscription Flow
POST /subscriptions
CreateStandardSubscription
(using plan_id
from product) OR CreateCustomSubscription
(defining schedule).invoice_items
array (one item for standard, multiple for custom).SubscriptionBehaviour
(prepaid, grace period etc.).coupon_code
: (Optional).200 OK
containing the newly created SubscriptionDetail
object (likely with status: 'created'
). GET /subscriptions
Subscription
summary objects.GET /subscriptions/{id}
SubscriptionDetail
object) for managing a specific subscription.id
(Subscription ID)SubscriptionDetail
object.PUT /subscriptions/{id}
id
(Subscription ID)command: "update"
, command: "pause"
, or command: "revoke"
with relevant schema (Update...Subscription
, PauseSubscription
, RevokeSubscription
).SubscriptionDetail
object.