Getting started

Add the HTML

To get started, add the following HTML in the <head> of your page.

<script
  id="upzpdl"
  src="https://assets.upzelo.com/upzelo.min.js"
  appId="[App id from your Account]"
  customerId="[Customer Id from your subscription platform]"
></script>

This will:

Launch a cancellation flow on any button or link with id=’cancel’
Enable manual billing alerts (for automated billing processing see below).

The following attributes can be added to the above script tag.

attribute	type	description	default
`appId`	required	The ID of your Upzelo app account. e.g. `upz_123456789`
`customerId`	required*	The customer's ID, from your subscription platform. e.g. `cus_123456abc`	`rec_123456abc`
`mode`	optional	Which account mode to process cancel flows in.	'live'
`selector`	optional	A CSS selector for the button(s) you wish to trigger Upzelo.	'#cancel'

* customerId can be omitted if added later with JS.

Where to find your App ID

Inside your Upzelo account you’ll find your App Id in the “Setup Upzelo” area: https://upzelo.com/app/setup/complete-setupopen in new window.

Using upzelo.init()

If the above attribute values are not available to you in the HTML, you can add them with JS using window.upzelo.init(config), where config is a Upzelo config object.

For example:

<script
  id="upzpdl"
  src="https://assets.upzelo.com/upzelo.min.js"
  appId="upz_app_b9c70b638d48"
></script>

window.upzelo.init({
  customerId: "1233",
  selector: "button#unsubscribe",
});

Note that the appId is still required on the <script> tag.

Custom trigger events

You are free to open the Upzelo modal on an event of your choosing, using window.upzelo.open().

element.addEventListener("click", () => {
  window.upzelo.open();
});

You can also pass the Upzelo config object to allow different buttons to do different things.

element.addEventListener("click", () => {
  window.upzelo.open({ subscriptionId: "123" });
});

Signed Payload for Automated Processing

To verify the request is authorized by your website, Upzelo requires a hash that’s been generated on your server. Without this, Upzelo will notify you that a request has been made in the Requests area, but it won't automatically update your customers data with your payment provider.

The hash can be generated in many different backend languages using your API key and the customer ID.

Here’s an example in PHP:

<?php
echo hash_hmac("sha256", $customerId, $upzeloApiKey);

Then you need to pass Upzelo the hash when a cancel flow is started:

window.upzelo.init({
  hash: "***", // The hash generated previously
});

Your API key should not be exposed in the browser. If you believe it has been, you can reset it in Upzelo.

Note that `hash` is not a script parameter

in order to implement the "Complete Setup" with automated billing actions, refer to window.upzelo.init() instructions above.

Callbacks

If you wish to trigger your own code when an Upzelo flow has completed, you can add a callback function to the Upzelo config object. You might use this to reload the page, update the UI, send something to an API endpoint, or just about anything really.

The available callbacks are:

Next Steps

Live or Test mode

By default, the UpzeloJs script will connect in Live Mode. If you are creating a Test workflow for your staging website or application we recommend creating content in the Upzelo “Test Mode” account, which can be access via the sub-menu.

Untitled

Where do you want to launch a cancellation flow?

In most cases, your website or application will have a cancellation page with a <button> or link with an ID attribute of ‘cancel’. In this case, add the Single script tag below into the <head> of your website or application.

If you have buttons or links that have an ID attribute of 'cancel' that you don’t want to launch a cancellation flow, then you need to supply a custom selector. This will override the default and prevent loading a cancellation flow on those elements.

If you have multiple cancel elements on your website or application, you can supply multiple CSS selectors to the ‘selector’ attribute like so selector: 'button#cancel, a.cancel'

Customers with multiple subscriptions

Customers may have 1 or more subscriptions. To tell Upzelo which subscription a cancellation flow should apply to, you must include the Subscription ID. For example in your own platform UI or customer account page you may wish to offer multiple subscription cancellation buttons, each with the relevant Subscription ID mapped to the cancellation flow.

If no subscription ID is passed to Upzelo, then it will serve the customer flow to the subscriber but will not automatically process the outcome. If the customer is saved, or chooses pause or cancel this will appear in the requests panel for you to manually process in the subscription provider.

window.upzelo.init({
  subscriptionId: "[Subscription Id from your subscription platform]",
});

Customers with existing coupons

Customers imported from your subscription provider may already have active, expired, or one off coupons applied to a subscription. Upzelo will continue to present retention flows to these customers.

Customers that have been through a retention flow and previously accepted an offer may come back to the retention flow to cancel or try again to receive a discount offer. For this reason, if there is an active offer in the subscription's current billing period on any active subscription that customer will only be displayed the Default flow which only asks "Are you sure you want to Cancel?", and does not present offers.

To override this rule, an audience can be made that specifically includes a coupon, or coupons related to Upzelo offers previously accepted and then linked to a retention flow.

Customers that are not recognised

Sometimes, a retention flow is launched but the customer_id is not recognised by the Upzelo servers. This may arise because the customer record has been created recently and not yet processed by the payment provider connection Webhook method. Or, it's possible that there's been a synchronisation error. In this case, Upzelo loads the "Default flow" and posts the outcome into the "Requests" area, so that it can be processed manually. Upzelo will send the account owner user or manual processing contact applied in Settings an email notification.

# Getting started

# Add the HTML

# Using upzelo.init()

# Custom trigger events

# Signed Payload for Automated Processing

# Callbacks

# Next Steps

# Live or Test mode

# Where do you want to launch a cancellation flow?

# Customers with multiple subscriptions

# Customers with existing coupons

# Customers that are not recognised