Subscriptions early access
Snipcart lets you sell subscriptions and recurring plans on your site.
Another important note is that this feature is only available for merchants using Stripe as a payment gateway. We're working on adding support for other payment gateways.
In this section, you'll learn how to add recurring payments on your website.
Subscription vs plan
A subscription is represented by a combination of a plan and items.
Plan
The plan represents the payment schedule; you can define the interval for recurring payments, the interval count (every 2 weeks, every month, etc.). Different items can have the same plan.
Subscription
The subscription includes the selected plan and the selected items. The subscription is the link between the customer and the plan. Subscriptions can be viewed and managed in the merchant dashboard.
Customers can also view and manage theirs subscriptions in the customer dashboard.
Recurring order
A recurring order is created for each subscription payment. They will be clearly identified in the merchant dashboard.
Define a plan
To create a subscription, you'll first need to add a buy button to your site with specific attributes.
data-item-selected-planstring
The selected plan for the item. The value must be the plan's ID defined by data-planX-id.
If it isn't defined, the first plan will be selected automatically.
data-planX-idstring - Required
The plan's ID, it needs to be unique.
data-planX-namestring - Required
The plan's name. This information appears as the subscription's name in any emails, the merchant dashboard and the customer dashboard.
data-planX-frequency"Daily" | "Weekly" | "Monthly" | "Yearly" - Required
The payment frequency. This can be combined with the interval to allow more flexibility.
data-planX-intervalnumber
Defaults to 1
The payment interval, ie: if frequency is Weekly and interval is 2, the payments will be every 2 weeks.
data-planX-countnumber
The number of billing cycle before the subscription stops. If the count is not set, the subscription will renew indefinitely. This can be useful when you need to take a specific number of payments.
data-item-planX-pricenumber | multi-currency price
The item's price within the plan. This can be used to offer the same product at different prices depending on the selected plan. This attribute also supports multi-currency.
HTML buy button
<button class="snipcart-add-item"
data-item-id="painting_lessons"
data-item-name="1h painting class"
data-item-url="/painting_lessons"
data-item-description="Painting lessons - 1h"
data-item-selected-plan="weekly-plan"
data-plan1-id="weekly-plan"
data-plan1-name="1h / week for 1 session"
data-plan1-frequency="weekly"
data-plan1-interval="1"
data-plan1-count="10"
data-item-plan1-price="20"
data-plan2-id="biweekly-plan"
data-plan2-name="1h / 2 weeks for 1 session"
data-plan2-frequency="weekly"
data-plan2-interval="2"
data-plan2-count="5"
data-item-plan2-price="25"
>
Add to cart
</button>JSON schema if JSON crawler is used
{
"id": "painting_lessons",
"name": "1h painting class",
"url": "/paint_lessons",
"price": 30.00,
"description": "Painting lessons - 1h",
"availablePlans": [
{
"id": "weekly-plan",
"name": "1h / week for 1 session",
"frequency": "weekly",
"interval": 1,
"count": 10,
"itemPrice": 20.00
},
{
"id": "biweekly-plan",
"name": "1h / 2 weeks for 1 session",
"frequency": "weekly",
"interval": 1,
"count": 5,
"itemPrice": 25.00
}
]
}Subscription lifecycle
A subscription has a lifecycle, recurring payments are charged, some of them can fail, customers can decide to cancel, etc. The flowcharts below illustrate how this lifecycle is implemented.
First payment
Once a customer purchases a subscription, an initial payment will be charged, this will create a subscription and an order in the dashboard.
Recurring payment
Subscriptions will be charged based on the plan schedule. Each recurring payment will create an order in the dashboard. When a recurring payment fails, the customer will be notified and will need to update their payment method to pay the outstanding balance. An unpaid subscription will automatically be canceled at the next billing date.
Subscription cancelled
A subscription can be cancelled by the merchant via the merchant dashboard, or by the customer directly in the customer dashboard. Once a subscription is canceled, the subscription state is set to CancellationRequested, the subscription will remain active until the next billing date. The state will then be changed to Cancelled. This is important to consider this if you build on top of our feature.
Roadmap
The feature is still in early access, we are still actively working on improving it. Features on the roadmap include:
- Support more payment gateways and payment methods.
- Mollie
- Square
- Braintree
- Trial periods
- More flexible payments schedule based on iCalendar (RFC 2445) specification
- Discounts on recurring payments
- Configure the period of time that an unpaid subscription can remain active (grace period).
- Add multiple items to a subscription to support more complex use cases like food boxes, or build-your-own type of subscriptions.
- Possibility to purchase standard items (non-recurring) and subscriptions at the same time.
FAQ
Is shipping charged for every recurring payment?
Yes, the same shipping fees will be charged on every recurring order.
When checking out, I get the error that no payment method was found. Why?
At the moment, we only support Stripe. If there are no payment methods available during the checkout process, you are probably using another gateway.
What happens when a payment is declined?
When a payment is declined, the customer will get an email saying the payment failed. They will also be asked to update their payment method. They will have until the end of the billing cycle or 1 month (whichever comes first) to update their payment method and retry the payment. If at the payment deadline, the payment hasn't been made, we will cancel the subscription. This flowchart illustrates the whole workflow for a recurring payment, including when a payment is declined.