Subscriptions implementation

About Subscriptions

This page discusses the different available Subscriptions APIs and their specific implementation details.

The Overwolf Subscriptions APIs are several sets of endpoints, allowing 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.

Getting Started

To get started, it is important to choose the right API for you and your use-case

Subscription API

overwolf

checkout

headless

Implementation Overhead

Plan Management

Yes

No

Yes

Requires Baskets

No

Yes

Yes

Requires a Server

No

Yes

Yes

Implementation Details

Framework Independent

Yes

Yes

Yes

Can be Combined

Yes

Yes

Yes

Authentication

Any

Any

Any

Supported Plans

Subscriptions

Any

Any

Overwolf Subscriptions

The Overwolf Subscriptions API works by exposing a few simple endpoints, which the App can then interact with, in order to perform most common interactions with the Tebex Checkout API.

Sample App

For an example implementation of the Overwolf Subscriptions API, see the relevant sample app.

Creating an Overwolf App Tebex Store

The Tebex Checkout API requires an appropriate "Store" to be defined. To create a store:

• Head to the Tebex Control Panel, and make sure you have a registered account.
• Contact us to be given a link to create an Overwolf App type store.

Setting up webhook

To make sure that the store is synchronized with the Overwolf Subscriptions API, you MUST create a webhook linking the two:

• Head to the Webhooks Endpoints page (make sure you're viewing the right store).
• First of all - at the bottom of the page, you'll find the Secret Key, used for linking your store with the Overwolf Subscriptions API.
• Now, Create a new Endpoint, and mark ALL Webhook Types for it.
• For the Endpoint's URL, use https://subscriptions-api.overwolf.com/tebex-webhooks/${YOUR_PUBLIC_TOKEN}.

Setting up subscription plans

Package Deliverables

You MUST first configure a webhook before you can create a package.

The store is now set up, but it still needs to define packages that can be sold. To do that:

For Regular packages without upgrade/downgrade methods:

• Head to the Packages page (make sure you're viewing the right store).
• Create a package for every plan you wish to support, supplying it with all the details you want. Keep in mind that:
  • Pricing - The package MUST be set to Recurring Payment = Charge a recurring subscription, to ensure that it is an actual subscription.

For packages that support upgrade/downgrade methods:

• Head to the Packages page (make sure you're viewing the right store).
• Create a new Category, supplying it with all the details you want.
• Turn on the Enable Tiers button (This will enable the upgrade/downgrade system for all packages under that category).
• After the category creation, create a package for every plan you wish to support. Keep in mind that:
  • Category - The package MUST be set to the created category that support Tiers.
  • Pricing - The package MUST be set to Recurring Payment = Charge a recurring subscription, to ensure that it is an actual subscription.
  • Charge Customer Every - Packages under a tiered category must have the same billing time.

Store ID and Private Key

In order to link your store to the Overwolf API, you will need to know your store's public and private keys. These can be found in the API Keys page.

• Private Key - A private key, used by the Overwolf Subscriptions API.
• Public Token - Also called Store ID - A public key, used as your store's identifier with the Overwolf Subscriptions API.

Link store

To finish linking your Tebex Store with the Overwolf Subscriptions API, contact us. You will then be asked to provide the following:

{
  // Can be gotten [here](#store-id-and-private-key)
  public_token: '',
  // Can be gotten [here](#store-id-and-private-key)
  private_key: '',
  // Can be gotten [here](#setting-up-webhook)
  webhook_token: '',
  /**
   * Your App's UID.
   * - Overwolf Platform: Can be seen in the Overwolf Packages view window under your App's entry, under the `UID` field
   * - Overwolf Electron: Can be gotten [as follows](/ow-electron/getting-started/overview#fetching-your-app-id)
   */
  app_id: '',
  /**
   * Your desired deeplink scheme. This scheme will be used to notify you of the Checkout flow's progress.
   * - Overwolf Platform: Can be set using [url_protocol](/ow-native/reference/manifest-json#url_protocol-object)
   * - Overwolf Electron: See [Electron Deeplinks](https://www.electronjs.org/docs/latest/tutorial/launch-app-from-url-in-another-app)
   */
  deeplink_scheme: '',
}

Tebex Headless

The Tebex Headless API works by exposing several endpoints, allowing you to easily create baskets, manage the packages within them, and eventually produce a checkout link for the user to pay in, directly within your App.

However, you will still need to run your own backend server to receive webhooks on purchase updates, as well as manage the current subscription statuses for your different users.

For more information on implementing the Tebex Headless API, check out the official documentation

Tebex Checkout

The Tebex Checkout API works by exposing the raw endpoints used for any payment processing, giving you full control over the entire subscription flow, at the cost of requiring a dedicated backend server to manage every single part of it, with which your App and or website will interact.

For more information on implementing the Tebex Checkout API, check out the official documentation

* Note that currently, the Tebex Checkout API is still considered in beta. To get started using it, please contact Tebex Support

Implementation

Full API documentation for the Overwolf Subscriptions API is available here.

In order to actually implement subscriptions in your App, you need to implement the following three general flows:

• Checking the current status of all active subscriptions, affecting the App properly.
• Fetching a list of available subscription plans.
• Generating a Tebex Checkout link to let a user pay for a plan they want.

The exact implementation may vary drastically between Apps, in the same way that the plans themselves may differ. However, usually, it'll act in the following way:

• On App launch, check for the current subscription status, and initialize the different features accordingly.
• In a specific section of the App, show users a listing of all available subscription plans.
• If they choose to purchase a specific plan, open the relevant checkout link for them in their browser, where they can purchase it.
• Periodically, and especially after a successful subscription purchase, re-check the current subscription status, and change the App's behavior accordingly.