Subscriptions early access

Snipcart lets you sell subscriptions on your site.

At the moment, subscriptions in V3 are only available in early access. You can request access by writing to support@snipcart.com. Please, specify the email associated with your account so that we can grant you access.

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 subscriptions to your website.

Subscription vs plan

A subscription is the combination of a plan and items.

Items

The item is the product that will be purchased on a recurring basis. It can be either a digital or physical item. For now, a subscription can contain only one item, but we’ll support multiple items as part of a subscription eventually.

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.

subscription in dashboard

Customers can also view and manage their subscriptions in the customer dashboard.

customer dashboard

Recurring order
A recurring order is created for each subscription payment. They will be identified in the merchant dashboard.

recurring orders

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 - Required 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 - Required
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 cycles 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-price="30"
    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 planned 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. It 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 it. Features on the roadmap include:

  • Support for more payment gateways and methods.
    • Mollie
    • Square
    • Braintree
  • Trial periods
  • More flexible payments schedule based on iCalendar (RFC 2445) specification
  • Discounts on subscriptions
  • Grace period configuration (amount of time when unpaid subscription remains active).
  • Multi-items subscriptions (to support more complex use cases like food boxes or build-your-own type of subscriptions).
  • Purchasing standard items (non-recurring) and subscriptions at the same time.
  • Pause subscriptions

FAQ

Is shipping charged for every recurring order?

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 the payment of a recurring order 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 recurring order payment, including when a payment is declined.