Subscriptions

The pages in this section

What happens each billing period

1. Invo works out what the period is worth in coins. On the card rail that is the price times the platform peg of 10 coins per USD: a 9.99 USD period is worth 99.90 coins. On the Steam rail it is what that price buys through Steam for the member’s country, floored to whole coins (for example 69 coins for 9.99 USD in the US).
2. Invo spends the member’s existing wallet balance first.
3. If the wallet is short, Invo tops it up from the rail behind the subscription (the saved card, or the member’s Steam agreement) for the shortfall only, mints the coins, and then spends the full period amount from the wallet.
4. The coins spent are split between Invo’s platform fee and your revenue. The fee percentage is your game’s platform fee (10 percent by default; the remainder, 90 percent, is yours). On the card rail a fixed component of 0.30 USD is added to the fee on the card-funded portion of a renewal only; the wallet-funded portion carries the percentage alone. The exact figures are reported on every renewal event in the split block.
5. Invo settles your revenue to you through your normal partner payout. Invo never pays anyone else on your behalf (see revenue_share, which is attribution only).

The two clocks

Two different dates live on every subscription and must not be confused.

Statuses

“Live” means the subscription occupies the member’s one-live-subscription-per-item slot and will be touched by the renewal engine.

State transitions

A paid renewal always lands in active, whatever the subscription was before.

Which rail

A subscription’s rail is fixed at creation. A card cannot be attached to a Steam subscription and a Steam agreement cannot be attached to a card subscription.

Prerequisites

Your game must be live

Creating a subscription (/subscribe and /steam/init) requires the game to be in live status. A game in testing status is refused with 403 GAME_NOT_LIVE. A testing game may still read, list, cancel, reprice and change the card on existing subscriptions. Make the game live from the developer console before you create your first subscription, in sandbox as well as in production.

Keys, and which to use where

Every request carries your server-side secret in the X-Game-Secret-Key header. Two kinds of key are accepted in that header:

Both kinds carry a 7-day rotation grace: after you rotate, the previous key keeps working for 7 days. Keys are server-side credentials. Never ship them in a game client, a browser or a mobile app.

Base URLs

Production   BASE = https://invo.network
Sandbox      BASE = https://sandbox.invo.network/sandbox

# every path in this section is written against BASE:
POST $BASE/api/subscriptions/subscribe
#   sandbox:     https://sandbox.invo.network/sandbox/api/subscriptions/subscribe
#   production:  https://invo.network/api/subscriptions/subscribe

Subscribe to webhooks before you go live

Renewals, failures, authentication challenges, cancellations, expiries and refunds are all reported by webhook, and several of them carry data you cannot fetch any other way (for example the confirmation link on subscription.authentication_required). Register a target URL before you create a real subscription. See Webhooks.

Identity: what a member needs

A member is identified by player_email. player_name is required on create and is used only if the player does not exist yet in your game. player_phone is optional. If the phone you supply already belongs to a different identity on the platform, the create is refused with 409 PHONE_SHARE_APPROVAL_REQUIRED and a one-time code is sent to the phone’s current owner; the body carries approval_id, expires_at and next_endpoint for the approval flow.

Rate limits

Conventions used throughout

• All timestamps are ISO 8601 with an explicit offset, for example 2026-11-05T14:02:11.482913+00:00.
• All money and coin figures are JSON strings, never numbers ("9.99", not 9.99), so a parser cannot silently round them.
• Match on error_code (and on status where the body carries one), never on the human-readable message. Messages are illustrative and may be reworded.
• “Member” and “player” mean the same person: the end user your game bills. “Partner” and “developer” mean you.
• Where a shape on these pages disagrees with the API, the API wins and the page has a bug. Tell us.

Clients used by the samples

Every page in this section stacks the same five samples per call: curl, Node with the @invonetwork/web-sdk server client, Node over raw HTTP, Python with the invonetwork package, and Python over raw HTTP. The SDK samples assume the clients below; the raw HTTP samples assume the two helpers below and nothing else.

import { InvoServer } from "@invonetwork/web-sdk/server";

const invo = new InvoServer({
  gameSecret: process.env.INVO_GAME_SECRET!,   // server-side only
  baseUrl: process.env.INVO_BASE_URL!,         // https://invo.network  |  https://sandbox.invo.network/sandbox
});

const BASE = process.env.INVO_BASE_URL;            // https://invo.network  |  https://sandbox.invo.network/sandbox
const GAME_SECRET = process.env.INVO_GAME_SECRET;  // server-side only

async function invo(method, path, body) {
  const res = await fetch(BASE + path, {
    method,
    headers: { "Content-Type": "application/json", "X-Game-Secret-Key": GAME_SECRET },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  return { status: res.status, json };
}

import os
from invonetwork import InvoServer

invo = InvoServer(
    game_secret=os.environ["INVO_GAME_SECRET"],   # server-side only
    base_url=os.environ["INVO_BASE_URL"],         # https://invo.network  |  https://sandbox.invo.network/sandbox
)

import os, requests

BASE = os.environ["INVO_BASE_URL"]            # https://invo.network  |  https://sandbox.invo.network/sandbox
GAME_SECRET = os.environ["INVO_GAME_SECRET"]  # server-side only

def invo(method, path, body=None, params=None):
    r = requests.request(method, BASE + path,
                         headers={"Content-Type": "application/json",
                                  "X-Game-Secret-Key": GAME_SECRET},
                         json=body, params=params, timeout=30)
    try:
        return r.status_code, r.json()
    except ValueError:
        return r.status_code, {}