Subscriptions

The pages in this section

From a game secret to a reconciled renewal, in order

Every phase a partner goes through, the call that does it, and the page that covers it. Nothing on this list needs a conversation with Invo, in sandbox or in production; where a step needs the console it says so.

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 title’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 title must be live

Creating a subscription (/subscribe and /steam/init) requires the title to be in live status. A title in testing status is refused with 403 GAME_NOT_LIVE. A testing title may still read, list, cancel, reprice and change the card on existing subscriptions, and may save cards. You set the title to live yourself, from the developer console, in sandbox and in production alike; it is the same action in both, and no review is involved. A live title is what makes subscriptions sellable and transfers receivable, so do it before your first subscription in each environment.

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 client application, 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 title. 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.

Where a member comes from

A member exists in your title once any call that carries player_name has run for their email: /subscribe and /steam/init themselves, a currency purchase, a send or a transfer. The two card-capture endpoints (the hosted card page and /setup-intent) identify an existing member and answer 404 PLAYER_NOT_FOUND for an unknown one; they never create players. The order of operations for a brand-new member on the card road is spelled out on the card road.

Your game_id

The webhook registration call is addressed by game_id. Read it from the console on the title, or from any subscription object (subscription.game_id, a string). Once you know it, GET /api/dev/webhooks/games/<game_id> with your key returns the title’s current webhook subscription; the unscoped list GET /api/dev/webhooks/games takes a console session, not the key. Each environment has its own title and therefore its own id.

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 title 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. The SDKs are optional: everything on these pages is plain HTTPS with one header, and the raw samples are complete on their own.

npm install @invonetwork/web-sdk     # subscriptions, cards and the clock tools from 3.8.0;
                                     # cards.createSetupSession (the hosted card page) from 3.9.0. Node 18+.
pip install invonetwork              # subscriptions, cards and the clock tools from 3.7.0;
                                     # cards.create_setup_session from 3.8.0. Python 3.9+.

Typed results in the Node package are camelCase (result.firstCharge.paidPeriodSeq); the Python package uses snake_case attributes (result.first_charge.paid_period_seq). Webhook events parsed by either package keep the wire names (event.event_type, event.data.period_seq), because the body is the signed artefact.

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, {}