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:
- It is created and kept up to date in Google Play and the App Store. Product ids, prices per country and descriptions are sent to the stores for you.
- Your game client reads it, so the store screen no longer ships a fixed list.
- Purchases are checked by MultiConnectCloud with Google or Apple, and the product's grants go into the player's wallet (section 10) automatically.
Before you start
Each store needs a few things in place before it accepts products from MultiConnectCloud:
Google Play
- The app exists in Play Console.
- A build that includes Google Play Billing has been uploaded to any track. Internal testing is enough, and it doesn't need review. Until then, Google refuses to create in-app products for the app.
App Store
- The app exists in App Store Connect with its bundle id.
- Business → Agreements shows the Paid Apps agreement as Active, with banking and tax filled in. Until then, Apple refuses to create in-app purchases.
- The keys below are created under Users and Access → Integrations. The first time, the Account Holder must request access to the App Store Connect API. After that, a user with the Admin role can create the keys.
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:
- Choose a project with the project picker at the top left, or create one with New project.
- Search for Google Play Android Developer API in the top bar, open it and choose Enable.
- 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.
- Service account name: e.g.
- Copy the service account's email (
…@….iam.gserviceaccount.com). - Open the service account → Keys → Add key → Create new key → JSON → Create. A
.jsonkey 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:
- Open Users and permissions in the left menu, at the developer account level (not inside an app).
- Choose Invite new users and paste the service account email.
- Open App permissions → Add app, tick your app, and choose Apply.
- 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
- 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:
- 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.
- Copy the Issuer ID shown above the keys table.
- Choose + (Generate API Key). Set Name to e.g.
MultiConnectCloud Store Productsand Access to App Manager, then Generate. - 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:
- On the same Integrations tab, open In-App Purchase and choose Generate In-App Purchase Key (or +).
- Name it, e.g.
Purchase checking, and choose Generate. - 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:
- 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).
- 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.
- 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.
- 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:
- create the app itself;
- sign Apple's Paid Apps agreement and set up banking and tax;
- the first Apple in-app purchase submission, with an app version;
- make the review screenshot image (the dashboard uploads it);
- add licence testers (Play) and sandbox testers (Apple);
- upload the first Play build with billing.
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:
- When your IAP plugin reports a successful purchase, send its receipt to
McAppIap.ValidateAsync(receipt). - Wait for that call to succeed.
- 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:
- A receipt can be granted only once, and only to the player who sent it.
- Google licence-tester and Apple sandbox purchases are granted and marked as tests.
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:
- the
productKey, the store'stransactionId,isSandbox, and the product'sgrantsJSON; repeated= true when this player's purchase was checked before.
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.
- 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.
- 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.
- Your API answers 2xx once it has paid: the client's call succeeds, with
grantedBy= "game", and the client confirms the purchase. - Anything else, or no answer within 10 seconds, makes the client's call fail, so the purchase stays pending and is retried. The retry sends the same event again with the same
transactionId, so pay once pertransactionId.
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:
- With a webhook set up (Route 2 above), every sync that changes the catalog also sends a
catalog.changedevent with the newcatalogVersion. - That event is best effort, so keep a slow poll of
GetCatalogVersionAsyncas well, e.g. every few minutes, and read the full catalog only when the number changes.
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.

