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 charges the rail behind the subscription. On the card rail the saved card is charged the full price every period (card only since 2026-09-17); the coins it buys are minted and spent in the same step, so the member’s wallet never pays for a card subscription and never moves. On the Steam rail Invo spends the member’s existing wallet balance first and tops it up from the member’s Steam agreement for the shortfall only.
3. The period’s coins are split between Invo’s platform fee and your revenue. The fee on a card charge is your title’s subscription rate plus a fixed amount per charge, set by your tier: 4.5 percent plus 0.30 USD on the Open tier (the default) and 5.5 percent plus 0.50 USD on the Merchant of Record tier (see Tiers). That is a different rate from the fee on item purchases, which is 10 percent, and the two move independently. The fee is charged on the listed price (before tax) of every card charge: on the Open tier a 9.99 USD period pays Invo 0.75 and you 9.24, and a 100.00 USD period pays Invo 4.80 and you 95.20; on the Merchant of Record tier the same 9.99 period pays Invo 1.05 and you 8.94. On a card issued outside the United States, 1.5 percent of the listed price (before tax) is charged to you on top of the fee on either tier (0.15 on a 9.99 period), reported on each renewal as split.international_card_fee_usd. Fraud screening and the chargeback guarantee are included. These card terms apply to INVO card charges only; purchases through a third-party storefront or payment rail are unaffected. A negotiated subscription rate on your agreement replaces the percentage; the fixed amount stays your tier’s. On the Steam rail the fee is 7 percent of what the coins are worth, with no fixed amount. The exact figures are reported on every renewal event in the split block, where invo_fee_percent is the EFFECTIVE percentage including that fixed component, so on small periods it reads higher than the tier rate. Read the amounts rather than the percentage.
4. 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).

Who is the seller, and who handles tax

Every developer account is on one of two tiers. The tier decides who is the seller of your subscriptions to the member, and so who is responsible for tax on them. The subscription API, the events and the billing clock are the same on both. The full comparison is on Tiers.

Your tier is set per developer account, not per title. Whatever the tier, the split block on each renewal carries the fee that was actually taken; read it rather than recomputing it.

On the Merchant of Record tier Invo also issues a receipt for every card charge and a refund receipt for every card refund, emailed to the member when their email is known. The number and link reach you as receipt_number and receipt_url on subscription.renewed, subscription.refunded (the refund receipt) and a paid first_charge; they are absent on the Open tier and on Steam. And a chargeback reserve holds part of your share of each card charge (10 percent for 90 days by default) before it becomes available to withdraw; the split on the event is unchanged. See receipts and the reserve.

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 lands in active, whatever the subscription was before, with one exception: the trial charge of a paid trial keeps the subscription trialing while the trial window is still running. active arrives when period 2, the first regular-price period, is paid.

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, refunds and refund requests 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, the hosted card page mint (/api/checkout/card-setup-sessions), a currency purchase, a send or a transfer. Without player_name the hosted card page answers 404 PLAYER_NOT_FOUND for an unknown member; /setup-intent never creates 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, {}