The Detail Layout for Subscriptions displays details of the Subscription Product and also a Form for creating/editing Subscription Orders

Introduction

A Subscription Detail Layout allows you to display detailed content about an individual Subscription product to a customer. It also is an important part of outputting a Subscription Sign Up Form, as these must be outputted within the Layout of the Subscription they will subscribe Users to.

Outputting the Detail View

The most common place where Detail Views are displayed is on the automatically generated Detail Page, if you have enabled these. However, they can also be outputted within most Liquid files, including ordinary Pages.

Setting up Detail Pages

Heading to ECOMMERCE > Settings will allow you to select the Subscriptions tab.

Here you can set up Detail Pages by:

• Choosing the slug which will begin the URL to Subscription Detail Pages

• Choose a Page Template to use on Subscription Detail Pages

• Choose a Detail Layout to use on Subscription Detail Pages

Outputting on a Standard Page (or in most Liquid files, including Emails)

You can use the type parameter to output a Detail Layout in most Liquid files:

{% include "module", id: "14/subscription"
   item_ids: subscription_id
   type: "detail", layout: 'my_layout'
%}

Parameters:

• type - give the value

• 'detail'.

• layout - give the name of a Detail Layout for Subscriptions

• item_ids - this parameter is usually optional, but it's essential when you are outputting a Detail View as only one Item ID must be displayed.

Bear in mind that Forms will not work properly inside Emails, so if displaying a Detail Page inside an Email, it is best to provide an alternative Detail Page without the Sign Up Form.

Outputting on the Subscription Action Required System Page

To output the Layout here, you need to add a Detail Layout name to the Liquid as a parameter. Read more here.

File Structure

Subscription Layouts can be found at the path: layouts/modules/module_14/subscription Within this folder, you can create a folder for each Layout. Each Layout folder can contain a further "detail" folder containing the wrapper and item files it needs.

Developing the Detail Layout

Step 1 - Optional - Add logic to inform the User of what the status of their Subscription is currently.

We provide an example of some logic you can use to explain to logged in Users what the Form will do:

{% if context.params.slug == "subscription-action-required" %} 
    
    {% comment %} Content to display when customer is responding to an email notification which asked them to update or authorise payment details. {% endcomment %} 

{%- elsif active_subscriptions contains this.id and context.current_user.id -%} 

    {% comment %} Content to display when customer has already signed up to this subscription and its status is active. {% endcomment %} 

{% elsif subscription_order_id and context.current_user.id %} 

    {% comment %} Content to display when customer has already signed up to this subscription and its status is not active. {% endcomment %} 

{%- else -%} 

    {% comment %} Content to display when the User is not logged in or has not yet signed up to this subscription. {% endcomment %} 
				
{%- endif -%}

In the case where the User is not currently logged in and is not responding to an email, the logic won't be able to determine the exact status straight away.

Instead, if a non-logged in User tries to Sign up for a Subscription, Siteglide will first log them in and check if they have an active Subscription already. If they do, we'll throw an error, but allow the User to try again if they wish to update their payment details.

Step 2 - Create your Form

Adding a Form to the Detail Layout allows users to Sign Up to this Subscription product. You can read more about creating this Form here.

If you've already created your Form, you can skip this step.

Step 3 - Include the Form inside the Detail Layout

Once you've created a Form and made a note of its ID, you'll be able to add it to your Detail Layout.

{% comment %} INSERT YOUR PAYMENT FORM HERE {% endcomment %}

This is just a suggestion, you can actually include your Form anywhere you like in the Layout. Use the following Liquid:

{% include 'form', id: '1', layout: 'my_form_layout' %}

Parameters:

• id - the ID of your Subscription Sign Up Form, you can check this in CMS > Forms. Remember you can use the same Form Layout for all Subscriptions. The this.id field controls which Subscription product is associated with the Form.

• layout - Choose a Form Layout

Step 4 - The Wrapper

The wrapper.liquid file could be used to add any HTML structure you may require around your layout.

You must include the following Liquid, which will output the item.liquid file for the Subscription Item. Most fields are specific to the Item and will only be available inside the item.liquid file.

{%- include 'modules/siteglide_ecommerce/ecommerce/get/get_subscriptions'
    item_layout: 'item' 
-%}

Step 5 - Available Fields

On the Subscription Detail View, we provide you with fields relating to the Subscription and also the Subscription Order for a logged in User.

Subscription Fields

• {{this}} - Output all fields as JSON

• {{this.id}}

• {{this.weighting}}

• {{this.release_date}}

• {{this.expiry_date}}

• {{this['Description']}}

• {{this['Interval']}}

• {{this['Interval Count']}}

• {{this.full_slug}} - URL for the Product Detail Page

• {{this['Secure Zones']}} - Array containing the IDs of Secure Zones associated with this Subscription.

• {{this.price.id}}

• {{this.price.currency}}

• {{this.price.price_charge}} - The chargeable price of this Subscription each Interval. Integer format.

• {{this.price.price_display}} - A field for displaying a secondary price of your choice, e.g. recommended retail price. This is not used by the integration. Integer format

• {{this.price.currency_symbol}}

• {{this.price.price_charge_formatted}} - The chargeable price of this Subscription each Interval. Currency format

• {{this.price.price_display_formatted}} - A field for displaying a secondary price of your choice, e.g. recommended retail price. This is not used by the integration. Currency format.

*Subscription Order Fields *If a User is logged in, Siteglide will establish if they have an existing Subscription Order for this Product. Using any of these fields should be done cautiously, as they will not be available if the User is logged out, or if they don't have an existing Subscription.

To determine this, you can use Liquid Logic to hide an entire block of code in which you use these fields:

{% if subscription_order != blank %}
  {% comment %}Content here can safely include subscription_order fields- 
  or will be hidden if none is available.{% endcomment %}
{% endif %}

Fields:

• {{subscription_order}}- Output all Subscription Order fields as JSON

• {{active_subscriptions}}- Array containing all Subscription IDs connected with one of the current User's Subscription Orders, where those orders have status Active

• {{subscription_order['Status']}} - These relate to the Subscription Status in Stripe and are the best way to understand the status of the Subscription Order at a glance. More information available below.

• {{subscription_order['Stripe Subscription ID']}} - This refers to a Subscription on Stripe and can be searched by the Client on the Stripe Dashboard to find out detailed information about this Subscription Order and the associated customer, invoices, payment_intents and charges.

• {{subscription_order['Cancel At Period End']}} - "true" or "false"- if true, this Subscription has been set by the User to be automatically Cancelled at the end of the current billing period. The User has a chance to change their minds until this date.

• {{subscription_order['Stripe Plan ID']}} - The Stripe ID for the Plan this Subscription Order is using. This may be an older plan than the current plan used by the Subscription product.

• {{subscription_order['Plan Chargeable Price']}} - A snapshot of the Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{subscription_order['Plan Display Only Price']}}- A snapshot of the Display Only Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{subscription_order['Plan Chargeable Price Formatted']}} - A snapshot of the Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product. Formatted as a decimal (e.g. 1.00).

• {{subscription_order['Plan Display Only Price Formatted']}} - A snapshot of the Display Only Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product. Formatted as a decimal. (e.g. 1.00)

• {{subscription_order['Plan Interval']}} - A snapshot of the Interval of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{subscription_order['Plan Interval Count']}} - A snapshot of the Interval Count of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

*Tip: Changes in the Pricing Plan *It's possible to change the price and billing interval of a Subscription. This change will only affect new subscribers and existing customers will continue on the plan they signed up for originally. You can read more about this here: eCommerce Subscriptions - Changing the Price and Billing Interval

When outputting fields, be aware that the Price might have changed globally for a Subscription, while a User may already have an existing Subscription with a different price. When changing their payment Details on the Subscription Detail View, these Users may be reassured to see the price displayed they are paying currently.

For these Users (if they are logged in) there will be two sets of fields available. For example:

• {{this.price.price_charge}} - Shows the current price of the Subscription if a new User were to sign up now.

• {{subscription_order['Plan Chargeable Price']}} - This field, if it is available, shows the price of the older plan that this customer is currently paying. See Subscription Orders in the next section for more of these fields.

You can use logic to display a different price to Users in this situation.

{% if subscription_order['Plan Chargeable Price'] != blank %}
  <p>{{subscription_order['Plan Chargeable Price']}}</p>
{% else %}
  <p>{{this.price.price_charge}}</p>
{% endif %}

Or alternatively, you can use the default filter:

<p>{{subscription_order['Plan Chargeable Price'] | default: this.price.price_charge}}</p>

Tip: Working with the interval As you can see above, there are multiple fields involved in storing the interval of charges, which you can use to display the interval in a user-friendly way. Here's one example of using Liquid to programmatically decide the format to display the Interval:

{% if this['Interval Count'] == "1" %}
  per {{this['Interval'] | pluralize: 1}}
{% else %}
  (every {{this['Interval Count']}} {{this['Interval']}})
{% endif %}

If the Interval Count is 1, it will use formatting like "per day".

If the Interval Count is greater than 1, it will use formatting like "every 2 days".

Check out all the available Liquid filters over on the platformOS Liquid docs.

Introduction

Most database items in the Siteglide database can be safely edited without affecting existing customers. For example, you can change the price of a physical product and everyone would expect to pay the new price for the product in future.

For Subscriptions, we've set it up so that Price changes on a Subscription will not affect existing subscribers. Instead only new subscribers will have to pay the new price.

Currently, we don't support allowing customers to choose their Plan when signing up to a Subscription. Instead, only the most recently created Plan will be available for new customers. We may add this functionality in the future, but for now, we suggest creating separate Subscription items with different periods and chargeable prices if you want to give customers different payment options for the same services.

Glossary

• Subscription (on Siteglide) - equivalent to a Product on the Stripe Dashboard - This is a Subscription Product which can be connected to a Plan. Plan (on Siteglide) - equivalent to a Plan on the Stripe Dashboard. This defines the price charged and the interval between charges.

• Subscription Order (on Siteglide) - equivalent to a Subscription on the Stripe Dashboard - This is a record of the order a customer has made to subscribe to a Subscription. It holds a record of the Plan and Pricing that the customer originally signed up for. It also has a status, which keeps track of whether this Subscription Order is "Active". Creating a New Plan Changing the Price of a Subscription will Create a new Plan There are three main variables that will affect the amount users will pay for a Subscription:

• Chargeable Price

• Interval

• Interval Count Changing the "chargeable price" will create a new Subscription Plan on Stripe and make this the default Plan for new customers.

Changing the Interval or Interval Count will not trigger an API call to Stripe to create a new Plan on its own.

If you want the new Plan to have a new Interval you should follow the following steps:

1. Change the Interval and/or Interval Count on Siteglide

2. Save the Chargeable Price in the prices tab on Siteglide. This will create a new Plan which will include the new values for Interval and Interval Count. (Changing the price before saving is optional- all that's needed to create the new Plan is to "save" the prices tab- you can leave it the same if you wish).

How a new Plan affects existing customers

Existing customers will not be affected by the new Plan. Their Subscription Order will be connected to the original Plan they signed up to.

How a new Plan affects new customers

New customers will not be shown information about the old Plan. They will sign up to the newest Plan only.

Our integration with Stripe Billing allows you to create Subscription Products and bill customers on a regular basis.

This section gives you a detailed understanding of the different tool options and functionality.

The customer can schedule their Subscription to end, while continuing to use services until the end date.

Introduction

Ending a Subscription is not as simple as deleting most database objects. The customer may wish to arrange for their Subscription to end, but they may wish to continue using the services they've paid for until the end of the billing period!

Front-end cancellation

When a User "cancels" a Subscription front-end, we send an API call to Stripe, instructing them to mark the Subscription to be cancelled at the end of the current billing period.

Subscription Orders marked for cancellation will have the field "cancel_at_period_end" ("module_field_14/subscription_order_9") marked as "true". This corresponds to the equivalent property on Stripe.

The following Liquid can be added within a user_subscriptions List Layout:

You may wish to use logic to only show the button when it can be used.

Un-scheduling the Cancellation before it happens

Until that time, we'll allow Users to change their mind and choose not to cancel the Subscription after all. This removes the property from the Stripe subscription cancel_at_period_end and the Subscription will remain in its current state: `

`

You may wish to use logic to only show the button when it can be used.

Both buttons could be combined in the logic as follows:

Cancelling Immediately

The option to cancel a Subscription item immediately is available on the Stripe Dashboard.

Stripe's Webhook

When the actual change of status to canceled takes place on Stripe, either because of an action on the Dashboard, or because Siteglide queued it to happen at the end of the billing period, Stripe will send a customer.subscription.deleted event to Siteglide. We'll then also remove the database object from your Site, and stop provisioning the Secure Zone Access.

Customise the Email and Landing Page used to take updated payment methods and authorisation from Subscription customers.

Introduction

When a Stripe subscription changes status, a customer may need to update their payment details or carry out 3D Secure authorisation.

The email and landing page used in this flow can be customised and branded.

The Email

You can find the System Email under Site Manager > System Emails with the name Subscription User Action Required.

The purpose of this Email is to inform the User that the Subscription Order needs action from them before it can continue to be processed.

Adding a Link to the Landing Page

You must add a link to the Landing Page where your customer can take action. You can use the Liquid below:

Parameters:

• button_text - sets the text displayed on the button

• button_id - optional - allows you to set the ID of the button

• button_class - optional - allows you to set the class of the button

Available Fields

Subscription Order Fields

• {{data.subscription_order}} - Output all available fields as JSON (except the new_subscription_status - see below).

• {{data.subscription_order['User ID']}} - The ID of the customer in Siteglide.

• {{data.subscription_order['Subscription ID']}} - The ID of the Subscription Order in Siteglide.

• {{data.subscription_order['Status']}} - The previous status of the Subscription Order before the update that triggered this Email

• {{data.new_subscription_status}} - the new status of the Subscription Order. This is the Event which will have triggered the Email.

• {{data.subscription_order['Stripe Subscription ID']}} - The ID of the Subscription in the Stripe Dashboard.

• {{data.subscription_order['Cancel At Period End']}} - "true" or "false"- if true, this Subscription has been set by the User to be automatically Cancelled at the end of the current billing period. The User has a chance to change their minds until this date.

• {{data.subscription_order['Stripe Plan ID']}} - The Stripe ID for the Plan this Subscription Order is using. This may be an older plan than the current plan used by the Subscription product.

• {{data.subscription_order['Plan Chargeable Price']}} - A snapshot of the Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{data.subscription_order['Plan Display Only Price']}} - A snapshot of the Display Only Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{data.subscription_order['Plan Chargeable Price Formatted']}} - A snapshot of the Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product. Formatted as a decimal (e.g. 1.00).

• {{data.subscription_order['Plan Display Only Price Formatted']}} - A snapshot of the Display Only Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product. Formatted as a decimal. (e.g. 1.00

• {{data.subscription_order['Plan Interval']}} - A snapshot of the Interval of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{data.subscription_order['Plan Interval Count']}} - A snapshot of the Interval Count of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

Subscription Fields

• {{data.subscription_order.subscription}} - Output all available fields as JSON

• {{data.subscription_order.subscription.name}} - The name of the Subscription Product

• {{data.subscription_order.subscription['Description']}}

• {{data.subscription_order.subscription['Image']}}

• {{data.subscription_order.subscription['Interval Count']}}

• {{data.subscription_order.subscription['Stripe Product ID (Live)']}} - The ID of the product in Stripe Live Mode

• {{data.subscription_order.subscription['Stripe Product ID (Test)']}}- The ID of the product in Stripe Test Mode

Customer Fields

• {{data.subscription_order.related_user}} - Output all available fields as JSON

• {{data.subscription_order.related_user.id}} - The ID of the User in Siteglide

• {{data.subscription_order.related_user.name}}

• {{data.subscription_order.related_user.first_name}}

• {{data.subscription_order.related_user.last_name}}

• {{data.subscription_order.related_user.email}}

When outputting fields in the email, Subscription Order fields beginning with the word "Plan" will normally be the appropriate choice. These will show the price that these Users will be paying- the original plan when they signed up.

Tip: Working with the Interval Fields As you can see below, there are multiple fields involved in storing the Interval of charges, which you can use to display the Interval in a user-friendly way. Here's one example of using Liquid to programmatically decide the format to display the Interval:

If the Interval Count is 1, it will use formatting like "per day".

If the Interval Count is greater than 1, it will use formatting like "every 2 days".

The Landing Page

You can find the System Page under Site Manager > System Emails with the name Subscription User Action Required.

The purpose of this Page is to provide a reliable URL where the above email can send Users to update their Payment Method. We'll provide the URL parameters to let the Page know which Subscription and Subscription Order to load. We'll also provide security to check that the User owns that Subscription Order before continuing.

This page may function very similarly to the standard Subscription Detail Page, however, you do have the option to use a different Layout or logic if you prefer.

Including the Subscription Detail Layout

The following Liquid will include a Subscription Detail Layout for the Subscription referenced in the link from the above Email. Note, this is different from the usual Liquid for including a Layout, because Siteglide will in this case be setting some of the parameters for you automatically.

Parameters:

• subscription_detail_page_layout - This allows you to choose which Detail Layout will be used for the Subscription Detail View. You can choose a different Layout than you use on your Subscription Detail Page.

If that Detail Layout contains a Form, we'll use the URL parameters to set the Form to edit the payment details for the correct Subscription Order referenced in the link from the Email.

You can add any other static content you like to this Page, but we recommend you use the Subscription Detail Layout itself to add any dynamic content and you can see available fields there.

This Article shows you how to use the Secure Zones Layout user_subscriptions to List Subscription Orders belonging to a User.

Introduction

This article shows you how to use the Secure Zones Layout user_subscriptions to List Subscription Orders belonging to a User. As this is a Secure user-specific List, the Layout is found in the Secure Zones Module.

This is slightly different from a Subscriptions List view, as this lists all available Subscription products- you can .

Outputting the user_subscriptions List

The following Liquid can be outputted on any Page protected by a Secure Zone:

Parameters:

• layout - Select a Layout for this view.

The user_subscriptions Layout

File Structure

You can find these Layouts at the path: layouts/modules/module_5/user_subscriptions/

Development

Looping over Subscription Orders

To loop over available Subscription Orders, you can use the following Liquid:

Inside the loop, you can use the available fields shown below under the this namespace. Outside of the loop Liquid, you can build the HTML structure which will wrap your Layout.

Setting a Subscription to Cancel at the end of the Billing Period

You can use the following Liquid to include a button to either cancel a Subscription or stop a pending cancellation. Read more here.

Available Fields

Subscription Order

• {{this}} - Output all available fields as JSON

• {{this.created_at}} - Outputs the time when this Subscription Order was originally created. Use the date filter with Ruby date format to format.

• {{this.last_edit_date}} - outputs the last time this Subscription Order was updated either via the Admin, user-action, or via Stripe Webhook. Use the date filter with Ruby date format to format.

• {{this.user_id}} - The ID of the customer in Siteglide.

• {{this.id}} - The ID of the Subscription Order in Siteglide.

• {{this.status}} - The previous status of the Subscription Order before the update that triggered this Email.

• {{this.cancel_at_period_end}} - Either 'true', false, or empty. If set to 'true' the Subscription will be cancelled at the end of the current billing period.

• {{this.stripe_subscription_id}} - The ID of the Subscription in the Stripe Dashboard.

• {{this.stripe_plan_id}} - The Stripe ID for the Plan this Subscription Order is using. This may be an older plan than the current plan used by the Subscription product.

• {{this.plan_chargeable_price}} - A snapshot of the Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product

• {{this.plan_display_only_price}} - A snapshot of the Display Only Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{this.plan_chargeable_price_formatted}} - A snapshot of the Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product. Formatted as a decimal (e.g. 1.00).

• {{this.plan_display_only_price_formatted}} - A snapshot of the Display Only Price of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product. Formatted as a decimal. (e.g. 1.00)

• {{this.plan_interval}} - A snapshot of the Interval of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

• {{this.plan_interval_count}} - A snapshot of the Interval Count of this Subscription Order's plan. This may be an older plan than the current plan used by the Subscription product.

Subscription

• {{this.subscription}} - Output all available fields as JSON

• {{this.subscription.name}} - The name of the Subscription Product

• {{this.subscription['Description']}}

• {{this.subscription['Image']}}

• {{this.subscription['Interval']}}

• {{this.subscription['Interval Count']}}

• {{this.subscription['Product Code (SKU)']}}

• {{this.subscription['Stripe Product ID (Live)']}} - The ID of the product in Stripe Live Mode

• {{this.subscription['Stripe Product ID (Test)']}}- The ID of the product in Stripe Test Mode

• The price of the Subscription Product per billing period:

Price

• {{this.subscription.price.currency}} - the currency

• {{this.subscription.price.currency_symbol}} - the currency symbol

• {{this.subscription.price.price_charge}} - the price charged per Interval as an integer.

• {{this.subscription.price.price_charge_formatted}} - the price charged per Interval as a decimal currency format.

• {{this.subscription.price.price_display}} - a display-only price per interval as an integer e.g. recommended retail price

• {{this.subscription.price.price_display_formatted}} - a display-only price per interval as a decimal currency format e.g. recommended retail price.

When outputting fields in the user_subscriptions view, Subscription Order fields beginning with the word "Plan" will normally be the appropriate choice. These will show the price that these Users will be paying- the original plan when they signed up.

Tip: Working with the Interval Fields As you can see below, there are multiple fields involved in storing the Interval of charges, which you can use to display the Interval in a user-friendly way. Here's one example of using Liquid to programmatically decide the format to display the Interval:

If the Interval Count is 1, it will use formatting like "per day".

If the Interval Count is greater than 1, it will use formatting like "every 2 days".

This view allows you to display available Subscription products for customers to browse through.

Introduction

The Subscriptions List View displays a list of Subscription products. Like other List Views, it can be sorted and filtered via Liquid.

This is slightly different from the user_subscriptions List view in the Secure Zones Module. This can be used to display a List of Subscription Orders belonging to a User. .

Outputting a List View

You can use the type parameter to output a List Layout in most Liquid files:

File Structure

Subscription Layouts can be found at the path: layouts/modules/module_14/subscription Within this folder, you can create a folder for each Layout. Each Layout folder can contain a further "list" folder containing the wrapper and item files it needs.

Developing the List Layout

The Wrapper

The wrapper.liquid file should be used to add any HTML structure you may require around your main list.

You must include the following Liquid, which will in turn loop over the Items and output the item.liquid file for each Subscription Item. Most fields are specific to the Item and will only be available inside the item.liquid file.

Fields

Subscription Fields

• {{this}}- Output all fields as JSON

• {{this.id}}

• {{this.weighting}}

• {{this.release_date}}

• {{this.expiry_date}}

• {{this['Description']}}

• {{this['Interval']}}

• {{this['Interval Count']}}

• {{this.full_slug}} - URL for the Product Detail Page

• {{this['Secure Zones']}} - Array containing the IDs of Secure Zones associated with this Subscription.

• {{this.price.id}}

• {{this.price.currency}}

• {{this.price.price_charge}} - The chargeable price of this Subscription each Interval. Integer format.

• {{this.price.price_display}} - A field for displaying a secondary price of your choice, e.g. recommended retail price. This is not used by the integration. Integer format.

• {{this.price.currency_symbol}}

• {{this.price.price_charge_formatted}} - The chargeable price of this Subscription each Interval. Currency format

• {{this.price.price_display_formatted}} - A field for displaying a secondary price of your choice, e.g. recommended retail price. This is not used by the integration. Currency format.

Prerequisites

Introduction

This Article will show all the additional steps you will need to take to set up the Stripe Payment Gateway in order to use our Subscriptions feature.

Step 1 - Activate your Stripe Account

Although you'll want to keep your Payment Gateway in Test Mode for now, you'll need to add the Live keys from your stripe account to your Siteglide account.

The reason for this, is that we'll be able to set products and plans up early so that when the time comes we'll be able to smoothly transition your Subscription Products from Test Mode to Live Mode.

The first step in doing this is to Activate your Stripe Account. https://stripe.com/docs/account This means completing a lengthy Form with information about the business that will own the account.

If you're just trying out Subscriptions, you may want to add the details of your Agency to the Stripe Account, but not put it live. If you're building a Site for a Client, it would be easiest to set up the Stripe Account for them- or to ask them to complete the Activation Form.

Step 2 - Add the Live Keys

In your Stripe dashboard you'll be able to find these keys under the Developers > API keys option in the left-hand menu, once you have toggled "View test data" off:

You'll need to add these keys to your Stripe Payment Gateway in the Siteglide Admin:

Step 3 - Set up the webhook endpoints in your Stripe Account

Our integration uses webhooks to get updates from Stripe on the status of your customers' subscriptions.

You'll need to set these up on the Stripe Dashboard with the "Viewing test data" toggle on. You will also need to set them up in Live mode- and you may decide to do this now so that you're ready.

Find Webhooks in the Stripe Dashboard menu under Developers > Webhooks:

Next, use the "add endpoint" button in the "Endpoints receiving events from your account" section.

After that, fill in the Endpoint URL and Events to send fields in the modal.

Whether setting up the test mode or the live webhook endpoint, you can start the URL with the Development domain for your Site, as I have in the example screenshot. If you're setting up the Live Endpoint, you could optionally use a custom domain. Add to this the following relative path: /api/stripe/subscription_updated For Events to send, you'll need to select both the customer.subscription.deleted and the customer.subscription.updated events. The same endpoint will handle both types of events.

Click the "Add endpoint" button to finish. Don't forget to set up the same webhook endpoint for Live mode as well, whether you want to do this now, or before you go live.

Step 4 - Add the Stripe Webhook Signing Secret to your Payment Gateway

This secret string is used by Siteglide to validate whether the incoming webhook calls are genuinely from Stripe.

You can find your Signing Secret on the Stripe Dashboard under Developers > Webhooks. If you've already set up your Live webhook, there will also be a Live Signing Secret and this should also be added to Siteglide.

It should be added to your Payment Gateway on Siteglide.

Step 5 - Check your Siteglide eCommerce Settings

Next we'll show you the Subscription related options under eCommerce Settings.

You can find the Subscriptions Settings under ECOMMERCE > Settings in the Menu and then navigate to the Subscriptions tab.

Currently, all Subscription Sign Up Forms must be outputted on a Subscription Detail page. You can use this opportunity to set the following:

• Subscription Slug - this sets the root of the URL for the Detail Page where customers will be able to Sign Up for this Subscription. The slug of each Subscription item will be appended on the end of the final URLs.

• Subscription Detail Page Template - This sets which Page Template will be used by the Detail Page

• Subscription Detail Layout - This sets which detail Layout folder will be used by the detail Page. You can use default until you decide to customise your own. These layouts can be found under SITE MANAGER > Code Editor under the path layouts/modules/module_14/subscriptions/

Step 6 - Check your Stripe Dashboard Settings

Stripe allows you a wide range of configuration options and settings you can use to enhance your experience. We'll aim to expand our integration to cover more of these options over time.

For now, we'll draw your attention to the key options which will have an impact on Siteglide.

Stripe Settings which will affect the Siteglide Integration In your Stripe Dashboard, navigate to Settings > Subscriptions and emails

Manage Failed Payments

In the "Manage Failed Payments" Section, you can set:

Retry Schedule - which allows you to determine how Stripe decides when to retry failed payments

Changing Subscription Status in any Section

Where Stripe allows you to set Subscription status in any section, you are free to decide the behaviour your Client needs. Siteglide's endpoint is watching for status changes in your Subscriptions and will update the Subscription Orders on Siteglide as appropriate.

3D Secure Payments with Subscriptions

In the "Manage payments that require 3D Secure" Section, Siteglide does support 3D Secure payments for Subscriptions, so you use any of the settings within.

A note on Emails

Siteglide currently sends transactional emails to customers only when their payment fails and an action is required, for example if 3D Secure authorisation is needed. We allow you to fully customise this System Email in Siteglide with dynamic content.

If you'd like to turn on any of Stripe's emails when any other event happens, these will not be connected with Siteglide and you'll need to read Stripe's documentation in order to style these.

What's next?

That's it! Your Stripe Account and your Siteglide Site are now ready to begin the integration.

Your Webhook Endpoint will send emails to customers whose Subscriptions experience payment failures or require further Strong Customer Authentication. Before going live, make sure to take a look at the System Page and System Email that will be displayed to these customers. You can learn more about these here.

We suggest that before going live with a Site that uses Subscriptions, you may wish to have a quick read of this doc again, to make sure that you've covered all the settings your Client needs.

For now, you'll probably want to get started creating Subscription Products.