Subscriptions API

The Overwolf Subscriptions API relies on a combination of endpoints and deeplinks, detailed in this page.

Endpoints

The following is a list of endpoints exposed by the Overwolf Subscriptions API, to handle the most common operations.

For live examples of the different endpoints, please check out the Tebex Subs Sample App.

For live examples of the new categories and upgrade/downgrade endpoint, please check out the Tebex Subs Sample App on the “upgrade/downgrade-develop” branch.

Checkout

Generates a checkout page for a specific subscription plan (package).

Request Type: 'GET'
Hostname: 'subscriptions-api.overwolf.com'
Path: '/checkout/${STORE_ID}/${PACKAGE_ID}'
Search Params:
  extensionId: string
  userId: string
  discordId (required when using discord actions): string

Result: 'Checkout Webpage'

This request redirects directly to the page, and as such, should be opened as a link in the users' browser.

Subscriptions

Returns a list of all active subscription plans (packages) for this App for the relevant user.

Request Type: 'GET'
Hostname: 'subscriptions-api.overwolf.com'
Path: '/subscriptions/${STORE_ID}'
Search Params:
  extensionId: string
Headers:
  Authorization: 'Bearer ${token}'

Result: 'Array of:'
  userId: 'string'
  packageId: 'number'

Packages

Returns a list of all available subscription plans (packages) for this App.

Request Type: 'GET'
Hostname: 'subscriptions-api.overwolf.com'
Path: '/packages/${STORE_ID}'
Search Params:
  extensionId: string

Result: 'Array of:'
  base_price: 'number'
  category: 
    id: 'number'
    name: 'string'
  created_at: 'string'
  description: 'string'
  disable_gifting: 'boolean'
  disable_quantity: 'boolean'
  discount: 'number'
  expiration_date?: 'string'
  id: 'number'
  image?: 'string'
  name: 'string'
  sales_tax: 'number'
  total_price: 'number'
  type: 'subscription | single'
  updated_at: 'string'

Categories

Returns a list of all categories and their associated packages available for a specific store in this App.

Request Type: 'GET'
Hostname: 'https://subscriptions-api.overwolf.com'
Path: '/subscriptions/${STORE_ID}/categories'
Search Params:
  extensionId: string
Headers:
  Authorization: 'Bearer ${token}'

Result: Array of:
  name: 'string'
  description: 'string' 
  active_tier?:
    tier_id: 'number'
    package:
      base_price: 'number'
      category:
        id: 'number'
        name: 'string'
      created_at: 'string'
      description: 'string'
      disable_gifting: 'boolean'
      disable_quantity: 'boolean'
      discount: 'number'
      expiration_date?: 'string'
      id: 'number'
      image?: 'string'
      name: 'string'
      sales_tax: 'number'
      total_price: 'number'
      type: 'subscription' | 'single'
      updated_at: 'string'
      prorate_price?: 'number'
      currency: 'string'
    active: 'boolean'
    created_at: 'string'
    next_payment_date: 'string'
    status:
      id: 'string'
      description: 'string'
  packages: Array of:
    base_price: 'number'
    category:
      id: 'number'
      name: 'string'
    created_at: 'string'
    description: 'string'
    disable_gifting: 'boolean'
    disable_quantity: 'boolean'
    discount: 'number'
    expiration_date?: 'string'
    id: 'number'
    image?: 'string'
    name: 'string'
    sales_tax: 'number'
    total_price: 'number'
    type: 'subscription' | 'single'
    updated_at: 'string'
    prorate_price?: 'number'
    currency: 'string'

Upgrade/Downgrade

Updates the package tier of a subscription package within a specific category for this App.

Request Type: 'PUT'
Hostname: 'https://subscriptions-api.overwolf.com'
Path: '/subscriptions/${STORE_ID}'
Search Params:
  extensionId: string
Headers:
  Authorization: 'Bearer ${token}'

Body:
{
// The tierId from the activeTier object received by the get categories method.
  "tierId": number,
// The packageId you want to change to.
  "packageId": number, 
// Whether to upgrade or downgrade to a package.
  "type": "upgrade" | "downgrade" 
}

Notes for Using the Categories and Upgrade/Downgrade Endpoints:

• To utilize the new Categories endpoint, you must create a new category and packages for that category in your Tebex store.

• If you have users subscribed to the "old" package type (which cannot be upgraded or downgraded), please implement the following UI changes in the subscription settings section of your app:

  • inform the user that he can’t switch between plans and must cancel his current plan first.
  • Allow the user to cancel his subscription and only then allow him to switch to the new package type that allows for Upgrading/Downgrading their package tier.

• When subscribing to the new package type, an initial purchase must be made using the Checkout endpoint. After the initial subscription, you can query the new Categories endpoint to check if the user has an active tier (subscription), and then display the Update/Downgrade buttons accordingly using the prorate_price.

Deeplinks

The following is a list of deeplinks used by the Overwolf Subscriptions API, to handle calls back to the application.

Success

Invoked when a user successfuly finishes the checkout flow.

`${YOUR_DEEPLINK_SCHEME}://?result=success`

Cancelled

Invoked when a user cancelled the checkout flow explicitly (does not fire if they closed the tab).

`${YOUR_DEEPLINK_SCHEME}://?result=cancel`