MultiConnectMultiConnectDocs Website home
MultiConnectSDK › SDK Apps

13. Store products and in-app purchases

What this feature does

Store products is your game's list of in-app purchases (coin packs, "remove ads", bundles), kept in one place on MultiConnectCloud. From there:

Before you start

Each store needs a few things in place before it accepts products from MultiConnectCloud:

Google Play

App Store

Each store uses its credentials for two jobs:

Job Google Play App Store
Create and update products A service account with Manage store presence An App Store Connect API key (App Manager)
Check purchases (Step 6) The same service account, with the financial permissions below An In-App Purchase key

The dashboard shows these steps too: open your app on SDK Apps, then Store products → Stores.

Step 1: Connect Google Play

1. Create a service account in the Google Cloud console:

  1. Choose a project with the project picker at the top left, or create one with New project.
  2. Search for Google Play Android Developer API in the top bar, open it and choose Enable.
  3. Open ☰ → IAM & Admin → Service Accounts and choose + Create service account.
    • Service account name: e.g. play-store-products.
    • Choose Create and continue, leave Permissions empty, choose Continue, then Done.
  4. Copy the service account's email (…@….iam.gserviceaccount.com).
  5. Open the service account → Keys → Add key → Create new key → JSON → Create. A .json key file downloads. Keep it private: it gives access to your Play account's API.

"Service account key creation is disabled"? Your Google Cloud organisation blocks keys by default. Open ☰ → IAM & Admin → Organization Policies, find Disable service account key creation (iam.disableServiceAccountKeyCreation), choose Manage policy → Override parent's policy, add a rule with Enforcement: Off, and Set policy. This needs the Organization Policy Administrator role.

2. Give it access in Play Console:

  1. Open Users and permissions in the left menu, at the developer account level (not inside an app).
  2. Choose Invite new users and paste the service account email.
  3. Open App permissions → Add app, tick your app, and choose Apply.
  4. Tick:
    • View app information (read-only)
    • View financial data, orders, and cancellation survey responses, for checking purchases
    • Manage orders and subscriptions, for checking purchases
    • Manage store presence, for creating and updating products
  5. Choose Apply, then Invite user.

A service account doesn't accept an invitation: it has access at once. Google can take several hours to apply new permissions, though. Until then, creating products or checking purchases fails with "The caller does not have permission".

3. Enter it on the dashboard: open your app on SDK Apps → Store products → Stores → Google Play:

Field What to enter
Package name Your app's package name, e.g. com.studio.game
Base region Two letters for the country of your base price, e.g. US
Choose the JSON key file The .json file from part 1

Choose Save and test. The card shows Connected when the key works.

Step 2: Connect the App Store

1. Create the App Store Connect API key, which creates and updates products:

  1. In App Store Connect, open Users and Access → Integrations → App Store Connect API → Team Keys. The first time, the Account Holder chooses Request Access and accepts the terms.
  2. Copy the Issuer ID shown above the keys table.
  3. Choose + (Generate API Key). Set Name to e.g. MultiConnectCloud Store Products and Access to App Manager, then Generate.
  4. Note the Key ID, and choose Download API Key (AuthKey_….p8). Apple lets you download it only once.

2. Create the In-App Purchase key, which checks purchases:

  1. On the same Integrations tab, open In-App Purchase and choose Generate In-App Purchase Key (or +).
  2. Name it, e.g. Purchase checking, and choose Generate.
  3. Note its Key ID and choose Download (SubscriptionKey_….p8). This one also downloads only once.

3. Find the app's Apple ID: Apps → your app → App Information → Apple ID, a number such as 6741234567.

4. Enter them on the dashboard: Store products → Stores → App Store:

Field What to enter
Apple ID (numeric) The number from part 3
Base territory Three letters for the country of your base price, e.g. USA
Issuer ID From part 1
Key ID The App Store Connect API key's id
Choose the .p8 file AuthKey_….p8
Purchase checking: Bundle id Your app's bundle id, e.g. com.studio.game
Purchase checking: In-App Purchase key id The In-App Purchase key's id
Purchase checking: Choose .p8 SubscriptionKey_….p8

Choose Save and test. The card shows Connected when the keys work.

You can connect one store now and the other later. A store that isn't connected shows "not connected" in the plan, and nothing is written to it. Connect it later, choose Plan again, and only that store's changes are listed.

Step 3: Fill the catalog

Add a product with Add product:

Field What it is
Product key Your name for it in code, e.g. coins_10k
Type Consumable (coin packs: can be bought again) or non-consumable (a one-time unlock)
Android product id, iOS product id The ids in each store. They cannot be changed or reused once created
Price One base price in the catalog's currency. Google converts it per country and Apple matches it to its price points. Add a Country override where you want a different price
Was price An optional struck-through "was" price
Text A title and description per Locale
Grants (JSON) What a purchase gives, as in section 10: {"currencies":{"coins":10000}}
Shown in the store screen Off hides it from players without removing it from the stores

Already have products in the stores? Connect the stores and choose Plan: products a store has and the catalog lacks are offered for import, matched by product id. If your game has its own product table, Import game table reads it as JSON.

Step 4: Plan, then apply

Nothing is written to a store until you ask:

  1. Plan compares the catalog with each store and lists every change: create, price change (old → new), text change, deactivate, no change, or blocked (with the reason).
  2. If a product was changed in two places differently, the plan shows both values and you choose. Nothing is written for that product until you do.
  3. Apply makes the changes in the background and shows each result as it finishes. Plans that create or deactivate products need the confirmation switch on first, because product ids cannot be changed or reused.
  4. Apply can be run again safely: it redoes only what is still different.

Products are never deleted from a store. Removing one from the catalog deactivates it on Google Play and removes it from sale on the App Store.

Apple products stop at "Ready to Submit". You submit them in App Store Connect, together with an app version the first time.

What only you can do in the store consoles:

When a store refuses a change

Apply lists each product once per side: Catalog (the change to your catalog on MultiConnectCloud) and one line per store. A failed store line leaves the catalog change in place. Fix the cause, choose Plan again, then Apply: only what is still different runs again, and nothing is created twice.

What the result says What it means What to do
Google Play: 403 The caller does not have permission The service account can't write products yet Check that Manage store presence is ticked for the app in Play Console. Check that a build with Google Play Billing is uploaded to a track. If you invited the account recently, wait a few hours
App Store: 403 or FORBIDDEN The API key's role is too low, or the Paid Apps agreement isn't active Use an App Manager key; check Business → Agreements
App Store: Ready to Submit Not an error: Apple products stop there Submit them in App Store Connect. The first ones go with an app version, from the version page's In-App Purchases section
App Store: missing review screenshot Apple needs one per product before submission Add a screenshot of your store screen in the product's dialog, at least the size of a phone screenshot

Test purchases: add licence testers in Play Console (Settings → License testing) and sandbox testers in App Store Connect (Users and Access → Sandbox). Their purchases are granted and marked as tests.

Step 5: Show products in the game

McAppStore.GetProductsAsync() returns the visible products for this platform, in display order, with the store id to buy with. It needs no sign-in.

Script 13.1: Load the store list

using MultiConnect.App;
using UnityEngine;

public class IapStoreScreen : MonoBehaviour
{
    private async void OnEnable()
    {
        var list = await McAppStore.GetProductsAsync("en-US");
        if (!list.Ok || list.Value == null) return;

        foreach (var product in list.Value.products)
        {
            // productId is this platform's store id: register it with your IAP plugin.
            Debug.Log($"{product.title} ({product.productId}): {product.basePrice} {list.Value.baseCurrency}");
        }
    }
}

Show the price your IAP plugin gives for each product where you can. That price is in the player's own currency, while basePrice is in the catalog's base currency.

Step 6: Check each purchase

Order matters:

  1. When your IAP plugin reports a successful purchase, send its receipt to McAppIap.ValidateAsync(receipt).
  2. Wait for that call to succeed.
  3. Only then confirm (consume) the purchase in the plugin.

If the call fails on a network error, the purchase stays pending in the plugin, and you retry on the next launch. The player never pays without getting their grants.

Script 13.2: Check a purchase, then confirm it

using System.Threading.Tasks;
using MultiConnect.App;
using UnityEngine;

public static class PurchaseCheck
{
    /// <param name="receipt">Your IAP plugin's receipt: Unity IAP's product.receipt, Google's purchase JSON, or an App Store transaction id.</param>
    /// <returns>True when the purchase was granted and may now be confirmed in the plugin.</returns>
    public static async Task<bool> Validate(string receipt)
    {
        var result = await McAppIap.ValidateAsync(receipt);
        if (result.Ok && result.Value != null)
        {
            Debug.Log($"Granted {result.Value.productKey}. Coins now {result.Value.Balance("coins")}");
            return true;
        }

        // Network: keep the purchase pending and retry on the next launch.
        // InvalidCredential: the store did not accept the receipt.
        // Forbidden: the purchase belongs to another player.
        // NotFound: the store product id is not in Store products.
        Debug.Log("Purchase not granted (" + result.Error + "): " + result.Message);
        return false;
    }
}

Who gets what:

If your game keeps its own coins

Script 13.2 pays the product's grants into the player's MultiConnectCloud wallet (section 10). A game that keeps balances in its own API has two other routes. Either way, MultiConnectCloud still checks the purchase with Google or Apple, and each purchase is paid exactly once, by whichever route checked it first.

Route How it works Choose it when
Your server checks The client sends the receipt to your game API. Your API calls McAppServer.VerifyPurchaseAsync, then pays its own coins Your API already receives the purchase from the client
MultiConnectCloud tells your API The client calls McAppIap.ValidateAsync as in Script 13.2. MultiConnectCloud sends a signed purchase.verified event to your API, which pays You want the client code from Script 13.2 unchanged

Route 1: your server checks. VerifyPurchaseAsync(playerId, platform, receipt) returns:

It records the purchase once, for that player only, and never touches the platform wallet. Pay once per transactionId, then answer the client so it can confirm the purchase in its IAP plugin.

Script 13.3: Game API: check a purchase and pay it from your own coins

using System.Threading.Tasks;
using MultiConnect.App;

public static class OwnCoinsPurchase
{
    /// <summary>The player id comes from the verified session (Script 6.3), never from the request body.</summary>
    public static async Task<bool> Handle(string playerId, string platform, string receipt)
    {
        var check = await McAppServer.VerifyPurchaseAsync(playerId, platform, receipt);
        if (!check.Ok || check.Value == null) return false;   // tell the client to keep the purchase pending

        // Your own grant, keyed by the store's transaction id so a retry pays once.
        await GrantFromOwnTable(playerId, check.Value.transactionId, check.Value.grants);
        return true;   // the client may now confirm the purchase in its IAP plugin
    }

    // Replace with your API's own wallet code: insert the transaction id with a unique index, then credit.
    private static Task GrantFromOwnTable(string playerId, string transactionId, string grantsJson) => Task.CompletedTask;
}

Route 2: MultiConnectCloud tells your API.

  1. On Store products, open Your game API. Enter your API's URL (https), choose Make a secret and store the secret in your API's settings.
  2. Under Who pays a purchase, choose Sends it to your game API to pay, then Save.

From then on, McAppIap.ValidateAsync checks the purchase, then POSTs a purchase.verified event to your URL. The body has playerId, platform, productKey, storeProductId, transactionId, isSandbox and grants.

Check every event's signature with McAppServer.VerifyWebhook, using the body exactly as received. It also refuses events older than 5 minutes, so a captured one can't be replayed later.

Script 13.4: Game API: receive purchase.verified (ASP.NET Core)

using System.IO;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using MultiConnect.App;

public static class MultiConnectEvents
{
    /// <summary>Map it with app.MapPost("/multiconnect/events", MultiConnectEvents.Receive).</summary>
    public static async Task<IResult> Receive(HttpRequest request)
    {
        var body = await new StreamReader(request.Body).ReadToEndAsync();
        var secret = "the secret from the dashboard, from your API's settings";
        if (!McAppServer.VerifyWebhook(body, request.Headers["X-MC-Timestamp"].ToString(), request.Headers["X-MC-Signature"].ToString(), secret))
            return Results.Unauthorized();

        using var json = JsonDocument.Parse(body);
        var kind = json.RootElement.GetProperty("event").GetString();
        var data = json.RootElement.GetProperty("data");

        if (kind == "purchase.verified")
        {
            var playerId = data.GetProperty("playerId").GetString() ?? "";
            var transactionId = data.GetProperty("transactionId").GetString() ?? "";
            var grants = data.GetProperty("grants").GetString() ?? "{}";
            // Pay from your own table, once per transactionId, then answer 200.
        }
        else if (kind == "catalog.changed")
        {
            // Re-read the catalog: McAppServer.GetStoreProductsAsync().
        }
        return Results.Ok();
    }
}

If your game API keeps its own product table

A game API that sells products from its own table can take part in the sync. Both calls use the server credential (section 6):

Call What it does
McAppServer.GetStoreProductsAsync() The whole catalog, with every field and catalogVersion
McAppServer.ReportGameCatalogAsync(basedOnVersion, products) Sends your table after you edit it, with the catalogVersion it was last brought up to. Its changes then show in the dashboard's plan
McAppServer.GetCatalogVersionAsync() Only the current catalogVersion: a cheap check of whether to read the catalog again

Knowing when the catalog changed:

Products your table leaves out are simply not compared. Leaving a product out of ReportGameCatalogAsync never removes it from the catalog or the stores; only removing it on the dashboard, or with archived = true, does.

The MultiConnect CLI can also read and sync the catalog: multiconnect products pull, plan and sync. See the CLI Guide.