Subscriptions implementation
Getting Started
To get started, it is important to choose the right API for your use-case. There are three types of Tebex integrations available for your app.
To review the different types of implementations, see the Subscription types table.
- Overwolf Subscriptions
- Tebex Headless
- Tebex Checkout
The Overwolf Subscriptions APIs are several sets of endpoints that allow app developers to easily integrate subscriptions into their apps using Tebex Checkout. Apps using this API can then access a simple subscriptions management system, without needing to worry about processing payments and keeping track of subscription statuses, and without the need for any server-side logic.
Sample app
For an example of how to implement the Overwolf Subscriptions API, see the sample app.
Setting up an Overwolf app
Prerequisites
- A registered account with Tebex.
Step 1: Create an Overwolf App
Tebex Store
To create a Tebex store:
- Login to your Tebex account and press Projects from the menu.
- Press Create another project.
- Enter the name of your project.
- Choose a currency. (default is USD)
- In the *Your project section, choose I have an Overwolf app.
- Check the agreements box, then press Continue, and then Confirm.
Once you have created your project, the apps integration keys are displayed. Make sure you copy them and keep them in a secure place, then press Continue for the next step.
Step 2: Setting up a webhook
Webhooks are required in order to make sure your store is working with the Overwolf Subscriptions API.
To create a webhook:
- Press Configure webhooks, then Setup webhooks.
- In the Endpoint URL, use
https://subscriptions-api.overwolf.com/tebex-webhooks/<YOUR_PUBLIC_TOKEN>
. - In the Webhook types, select all of the options, then press Add.
If the endpoint URL validation fails, you are not able to edit the URL and you need to delete the endpoint and try again.
Step 3: Setting up subscription plans
Once you have completed setting up the store, you are ready to create packages. You can create both tiered and non-tiered packages.
Creating categories
Create new categories based on the packages that you are offering.
- You must enable tiers in order to enable upgrade/downgrade options for packages.
- Once you have enabled tiers in your category, you are not able to disable this option.
- To allow users to change billing plans, you will need to first cancel the current subscription, and then have the user purchase the new subscription.
To create a category:
- In the left menu press Packages, then press Add new and select Category.
- Enter a name for the category of your package.
- Upload an image (optional).
- In the tabs below, enable the settings you need for your package(s).
General tab
In the General tab, enable/disable the following options:
- Tiers—enables upgrade/downgrade options for packages in the category.
- Parent category—choose a parent category. If there is no parent category, leave the default (Don't set this category as a subcategory of another).
- Package display formation— select from the drop down.
Visibility tab
In the Visibility tab enable/disable the following options:
- Only show if customer has purchased package— select an option from the drop down.
- Disable this category and remove it from the webstore—enable/disable.
- Order the packages in this category by price—enable/disable.
Cumulative tab
In the Cumulative tab enable/disable the following options: (only available when tiers are not enabled)
- Cumulate the purchases inside of this category—enable/disable.
- Disable cumulative packages that have a lower price—enable/disable.
Advanced tab
In the Advanced tab enable/disable the following options:
- Allow the customer to only purchase one package from this category—enable/disable.
- Delete pending expiry commands of other packages—enable/disable.
- Add any remaining time of other purchased packages—enable/disable.
- When the package has been configured, press Create.
Once you have created your category, you can create packages.
Creating packages
To create a package:
- When in a category, press Create a package. You can also pressAdd new, and select Package.
- Enter a name for the package.
- Enter a description of the package.
- Make sure your package is assigned to the correct category. If no category is assigned, select one from the drop down menu. If the category you need is not listed, follow the create a category step first.
- The package configuration menu changes based on the category that you assign it.
- You can't mix package types with different billing cycles in the same category. If you change a billing cycle for one package in the category, all the packages will update to the new billing cycle.
Packages with tiers
- In the Pricing tab, enter the price for the package, then configure the Remove from Customer after settings.
- In the Visibility tab, select dates from the calendar drop down for the Publish on webstore and Remove from webstore options. You can also use the slider to enable or disable Show this package to customers who haven't logged into the webstore and Display this package on the webstore and disable it entirely options.
- In the Variables tab, create a new variable. You are redirected to the New variables form.
- In the Goal tab, create a new community goal. You are redirected to the Community goals page. Press Create your first community goal to create a new goal.
- In the Webhooks tab, create a webhook that assigns custom data to the package.
- In the Discord actions pane, press + Discord actions to enable and configure Discord actions for the package.
Packages without tiers
- In the Pricing tab, enter the price for the package. Select a recurring payment option from the Recurring payment drop down, and then configure the Remove from Customer after settings.
- In the Limits tab, press Configure to configure the Global limit and the User limit settings. Use the slider to enable/disable Including packages that have been removed from customers when calculating limits option.
- In the Restrictions tab, select a package from the Require packages drop down, then use the sliders to configure the Require the customer to have purchased one package from the selected list and the Allow the customer to increase the quantity of this package when purchasing options.
- In the Visibility tab, select dates from the calendar drop down for the Publish on webstore and Remove from webstore options. You can also use the slider to enable or disable Show this package to customers who haven't logged into the webstore and Display this package on the webstore and disable it entirely options.
- Int he Gifting tab, use the sliders to enable/disable the Allow package to be purchased using gift cards and Allow this package to be gifted options.
- In the Variables tab, create a new variable. You are redirected to the New variables form.
- In the Goal tab, create a new community goal. You are redirected to the Community goals page. Press Create your first community goal to create a new goal.
- In the Upselling tab, to add Additional products, to Increase quantity, or offer Alternative products. Press +Add, then fill out the form including an image, the Package it belongs to, and the Offer price.
- In the Webhooks tab, create a webhook that assigns custom data to the package.
- In the Discord actions pane, configure what the customer receives when purchasing the package. Press + Discord actions to enable and configure Discord actions for the package. Press +File download +Gift card
Store ID and Private Key
To link your store to the Overwolf API, you need your store's public and private keys.
To see your store's API keys: In your Tebex store, in the left menu, press Integrations, then press API Keys.
You can only see the API keys of the project you are currently logged in to.
You can then view your keys:
- Private Key—the private key you need to pass to the Overwolf Subscriptions API.
- Public Token—called the Store ID. This is the public key used as your store's identifier and passed to the Overwolf Subscriptions API.
Link to store
To finish linking your Tebex Store with the Overwolf Subscriptions API, contact us. You need to provide the following:
- Retrieve from the Tebex store account.
public_token: ''
, - Retrieve from the Tebex store account.
private_key: ''
, - Retrieve from the Tebex store account.
webhook_token: ''
, - Your app's UUID:
- Overwolf Platform—retrieve from the Overwolf Packages view window under your App's entry, under the
UID
field. - Overwolf Electron—retrieve your Unique app ID.
- Overwolf Platform—retrieve from the Overwolf Packages view window under your App's entry, under the
- Your
app_id: ''
for the desired deeplink scheme. This scheme is used to notify you of the Checkout flow's progress.- Overwolf Platform—retrieve using the url_protocol.
- Overwolf Electron—retrieve using Electron Deeplinks.
The Tebex Headless API works by exposing several endpoints, allowing you to easily create baskets, manage the packages within them, and produce a checkout link for the user to pay in, directly within your app. You will need to run your own backend server to receive webhooks for purchase updates, as well as manage the current subscription statuses for your different users.
Contact Tebex support for more information on how to activate and use the Tebex Headless API. To read through the API, see the Tebex Headless API documentation.
The Tebex Checkout API is designed to allow creators to use Tebex's Merchant of Record platform without the need to use a Tebex-powered webstore.
Contact Tebex support for more information on how to activate and use the Tebex Checkout API. To read through the API, see the Tebex Checkout API documentation.
To get started using it, contact Tebex Support
Implementation
Implementations may vary based on your app and subscription plans. Typically the app flow will be as follows:
-
The current subscription status is checked at app launch and then it initializes the subscription's features.
Use the active subscriptions endpoint to retrieve a list of active subscriptions.
-
There is a dedicated section of the app that show users a listing of all available subscription plans.
Use the subscription plans endpoint to retrieve a listing of available subscriptions.
-
If the user chooses to purchase a specific plan, the relevant checkout link opens for them in their browser.
Use the Checkout link endpoint to generate the purchase link.
-
Return to step 1 after a successful subscription purchase.
For more information, see the API documentation for Overwolf Subscriptions.