Support
These docs are for v1.0. Click to read the latest docs for v2.0.

Subscribe Flow (Classic)

🚧

In Spring of 2016, we introduced a new subscribe flow builder, along with a survey builder. The below information reflects the traditional subscribe flow.

The Subscribe Flow handles your subscribers’ selection of a subscription product, any variants, and the term of their subscription. Cratejoy’s themes are set up to handle an arbitrary number of products and variants, and the most widely used combinations of term length and number. To handle this, we have many convenient filters and methods to handle subscribers’ product, variant and term choices.

Subscribers’ selections are handled by building a subscribe URL that corresponds to each decision point along the Subscribe Flow. The URL path consists of multiple ID-Value choice parts, where the IDs are unique Cratejoy IDs, and the Values are your product or variant names . These URL’s are provided by the product_subscribe_url filter.

EXAMPLE SUBSCRIBE FLOW

Suppose you had 2 products:

  • “Deluxe Box”
  • “Regular Box”

Each product has 2 product variants:

  • Flavor is “Savory” or “Sweet”
  • Gluten Restriction is “Gluten” or “Gluten Free”.

The terms available are:

  • “Month-to-Month”
  • “3 Month Prepay”
  • “6 Month Prepay”

Here is how an example checkout may take place on this store:

  1. Subscriber is on yourstore.com/subscribe
  • Subscriber is shown a list of products
  1. Subscriber chooses the “Deluxe Box” product
  2. Subscriber is sent to yourstore.com/subscribe/1111_Deluxe+Box
  • The Cratejoy platform knows there are 2 product variant types available for this product, so it asks which of the Flavor variant type’s values the subscriber wants.
  1. Subscriber chooses the “Savory” variant value
  2. Subscriber is sent to yourstore.com/subscribe/1111_Deluxe+Box/2222_Savory
  • Cratejoy platform knows there is a second product variant type available for this product, so it asks which of the GlutenRestriction variant type’s values the subscriber wants
  1. Subscriber chooses the “Gluten Free” variant value
  2. Subscriber is sent to yourstore.com/subscribe/1111_Deluxe+Box/2222_Savory/3333_Gluten+Free
  • Cratejoy platform knows that only one product instance exists with this combination of variants, so it asks which enabled term the subscriber wants
  1. Subscriber chooses the “6 Month Prepay” term
  2. Subscriber is sent to yourstore.com/subscribe/1111_Deluxe+Box/2222_Savory/3333_Gluten+Free/4444_6+Month+Prepay
  3. Since that selects a unique product instance and a term, Cratejoy will automatically redirect them to the secure checkout page with the subscriber’s selections in the cart.
  4. Subscriber is sent to yourstore.com/checkout to finalize the purchase.

It's important to realize that if on any step there's only one valid option, the Cratejoy platform will automatically select that option and forward the subscriber on to the next step. For example, if you have a single product, which has multiple variants, hitting yourstore.com/subscribe will send them directly to the variant selection for that product- -that is, yourstore.com/subscribe/1111_Deluxe+Box. If you have a single product with no variants and a single payment term, yourstore.com/subscribe will take them straight to checkout.

In addition to cases where there is only one product/variant/term, you might have a situation where you have multiple products, but only one is valid for their current state, such as if the subscriber used the yourstore.com/ac/COUPON_CODE route to add a coupon that only applies to a single product.

SUBSCRIBE FLOW CODE

The base template for handling the subscribe flow is subscribe.html. It handles determining what stage of the subscribe flow the subscriber is currently in, iterating over the options available for the current stage, then including the template for the current subscribe flow grid item. In a few themes, the individual product, term, and variant item code are in the html/subscribe_flow/ directory. The Cratejoy platform determines which stage the subscriber is on automatically based on the arguments to the subscribe route.

The stages of the subscribe flow are:

1. PRODUCT CHOICE

The subscribe_flow.html/product_grid_item.html typically contains the code that displays a single product option. It contains the formatting, image layouts, product name and description, as well as the subscribe stage link for selecting the product. The URL for the selection link for a product is produced by the product_subscribe_url filter

<a href="{{ product | product_subscribe_url(gift=gift) }}">

2. VARIANT CHOICE

At the Variant Choice stage, the subscriber has selected a product, and if the product has 1 or more variant, the Cratejoy platform asks for variant choices until a single product instance has been selected.

The subscribe_flow/variant_grid_item.html file typically contains the code that displays a single variant option. Its format is similar to the subscribe_flow/product_grid_item.html templates, except for a few variant specific changes, such as the format for the selection link URL for each variant value, which is

<a href="{{ product | product_subscribe_url(chosen_values, value, gift=gift) }}">

3. TERM CHOICE

At the Term Choice stage, the subscriber has selected a unique product instance, and if the instance has 1 or more enabled term choices, the Cratejoy platform asks which term the subscriber wants.

The subscribe_flow/term_grid_item.html contains the code that displays a single term option. Its format is similar to the subscribe_flow/product_grid_item.html and subscribe_flow/variant_grid_item.html templates. The format for the term selection link URL is:

<a href="{{ product | product_subscribe_url(chosen_values, term_price.term, gift=gift) }}">