Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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 Detail Layout for Subscriptions displays details of the Subscription Product and also a Form for creating/editing Subscription Orders
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.
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.
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
You can use the type
parameter to output a Detail Layout in most Liquid files:
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.
To output the Layout here, you need to add a Detail Layout name to the Liquid as a parameter. Read more here.
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.
We provide an example of some logic you can use to explain to logged in Users what the Form will do:
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.
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.
Once you've created a Form and made a note of its ID, you'll be able to add it to your Detail Layout.
As a guide, we've added a Liquid comment to remind you to add your Subscription Sign Up Form to this Layout: `
`
This is just a suggestion, you can actually include your Form anywhere you like in the Layout. Use the following Liquid: <div data-gb-custom-block data-tag="include" data-0='form' data-1='1' data-2='1' data-3=', layout: '></div>
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
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.
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:
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.
Or alternatively, you can use the default filter:
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 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.
This view allows you to display available Subscription products for customers to browse through.
The Subscriptions List View displays a list of Subscription products. Like other List Views, it can be sorted and filtered via Liquid.
You can use the type parameter to output a List Layout in most Liquid files:
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.
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.
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.
The Detail Layout for Subscriptions displays details of the Subscription Product and also a Form for creating/editing Subscription Orders
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.
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.
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
You can use the type
parameter to output a Detail Layout in most Liquid files:
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.
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.
We provide an example of some logic you can use to explain to logged in Users what the Form will do:
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.
If you've already created your Form, you can skip this step.
Once you've created a Form and made a note of its ID, you'll be able to add it to your Detail Layout.
As a guide, we've added a Liquid comment to remind you to add your Subscription Sign Up Form to this Layout: `
`
This is just a suggestion, you can actually include your Form anywhere you like in the Layout. Use the following Liquid: <div data-gb-custom-block data-tag="include" data-0='form' data-1='1' data-2='1' data-3=', layout: '></div>
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
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.
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:
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.
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.
Or alternatively, you can use the default filter:
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 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 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. .
*Subscription Order Fields *You'll see when developing a that when the User is logged in, it is also possible to access fields relating to a subscription_order the User has made for that Subscription product already.
This is not currently available on the List view- as the List view is designed as a way to browse Subscription products. To allow the user to view and manage their Subscription Orders, we recommend the .
To output the Layout here, you need to add a Detail Layout name to the Liquid as a parameter. Read more .
Adding a Form to the Detail Layout allows users to Sign Up to this Subscription product. You can read more about creating this Form .
*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:
Check out all the available Liquid filters over on the .
The customer can schedule their Subscription to end, while continuing to use services until the end date.
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!
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:<div data-gb-custom-block data-tag="-" data-0='ecommerce/subscription_cancel'></div>
You may wish to use logic to only show the button when it can be used.
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:
The option to cancel a Subscription item immediately is available on the Stripe Dashboard.
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.
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.
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.
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
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}}
*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 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.
The other Price and Interval fields stored against the Subscription, could be used to show how much the User is saving on their current plan compared to the current price. In the different context of the Subscription Detail Page- we give a different recommendation as here it may not always be possible to identify immediately if the User is subscribed to a different plan.
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".
Check out all the available Liquid filters over on the platformOS Liquid docs.
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.
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.