---
title: "Control store messages in Unity SDK"
description: "Choose when your Unity app shows App Store and Google Play messages about price increases, billing issues, and declined payments, so they don't interrupt a flow or onboarding."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

The App Store and Google Play sometimes need to show your users a message about their subscription:

- **App Store**: A request to consent to a price increase, a billing issue notice, or a win-back offer. By default, StoreKit shows these messages on its own while your app is open.
- **Google Play**: A notice that a subscription payment was declined and the payment method needs an update. Starting from SDK 4.3.0, the Adapty SDK requests these messages by default every time an `Activity` of your app starts after activation, including when the app returns to the foreground and when a flow or onboarding opens or closes.

Either way, a message can appear on top of a flow, an onboarding, or a checkout. To choose the moment yourself, switch the Adapty SDK to manual message handling, and call `Adapty.ShowStoreMessages` when a message won't interrupt the user.

:::warning
In manual mode, the stores don't show messages on their own. If your app never calls `Adapty.ShowStoreMessages`, users never see a price increase consent request, a billing issue notice, or a declined payment notice.
:::

## Before you start

You need:

- **Adapty Unity SDK 4.3.0 or later**: Earlier versions don't have the store messages API.
- **iOS 16 or later** for App Store messages: StoreKit doesn't deliver messages to apps on earlier versions. On iOS 15, `Adapty.GetPendingStoreMessageTypes` and `Adapty.ShowStoreMessages` fail with the `DecodingFailed` error, so if your app supports iOS 15, call them only on iOS 16 and later:

```csharp showLineNumbers title="C#"
#if UNITY_IOS && !UNITY_EDITOR
var iosMajorVersion = int.Parse(UnityEngine.iOS.Device.systemVersion.Split('.')[0]);
if (iosMajorVersion >= 16) {
    Adapty.ShowStoreMessages((error) => {
        // handle the error
    });
}
#endif
```

## Enable manual handling

To show store messages only when your app calls `Adapty.ShowStoreMessages`, call `SetStoreMessagesHandling` with `AdaptyStoreMessagesHandling.Manual` when you [activate the SDK](sdk-installation-unity#activate-adapty-module-of-adapty-sdk):

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetStoreMessagesHandling(AdaptyStoreMessagesHandling.Manual); // Auto is the default

Adapty.Activate(builder.Build(), (error) => {
    // handle the error
});
```

On iOS, the SDK then adds each App Store message to a pending list for the current app session. On Android, the SDK stops requesting Google Play messages on its own. With the default `Auto` value, the SDK doesn't capture App Store messages, so on iOS, `Adapty.GetPendingStoreMessageTypes` and `Adapty.ShowStoreMessages` have nothing to return or show.

## Get pending message types

On iOS, to find out whether any App Store messages are waiting, call `Adapty.GetPendingStoreMessageTypes`. It returns the types of the pending messages without showing or removing them:

```csharp showLineNumbers title="C#"
Adapty.GetPendingStoreMessageTypes((pendingTypes, error) => {
    if (error != null) {
        // handle the error
        return;
    }

    if (pendingTypes == null) {
        // Android: Google Play decides whether a message applies when you show it
    } else if (pendingTypes.Contains(AdaptyStoreMessageType.BillingIssue)) {
        // For example, skip the upsell and show the billing message first
    }
});
```

On Android, the method returns `null` without an error: Google Play doesn't report pending messages, and decides whether a message applies only when your app requests it. An empty list means that there are no pending messages on iOS. Until `Adapty.Activate` completes, the list is always empty.

Each App Store message has one of these types:

| Type | Message |
|:-----|:--------|
| `AdaptyStoreMessageType.Generic` | A general App Store message. |
| `AdaptyStoreMessageType.PriceIncreaseConsent` | A request to consent to a subscription price increase. |
| `AdaptyStoreMessageType.BillingIssue` | A notice about a subscription billing issue. Available on iOS 16.4 and later. |
| `AdaptyStoreMessageType.WinBackOffer` | An eligible [win-back offer](app-store-offers#win-back-offers). Available on iOS 18 and later. |

New StoreKit message types arrive with a `RawValue` of `storekit_<number>`. To check a type, compare it with `==` to one of the values above, and handle any other value as a type the SDK doesn't recognize.

## Show messages

When your app reaches a point where a store message won't interrupt the user — for example, after the user closes a flow or finishes onboarding — call `Adapty.ShowStoreMessages`:

```csharp showLineNumbers title="C#"
Adapty.ShowStoreMessages((error) => {
    if (error != null) {
        // handle the error
    }
});
```

- **iOS**: The SDK shows the pending messages one after another. After StoreKit shows a message, the SDK removes it from the pending list. If StoreKit fails to show a message, the SDK keeps the message for the next call and continues with the other messages.
- **Android**: The SDK requests Google Play messages for the current `Activity`. Google Play decides whether a message applies to the user, so a request doesn't always show a message. If the user fixes their payment method from the message, the SDK syncs the user's purchases with Adapty, and your [profile listener](unity-listen-subscription-changes) receives the updated access level.

### Show messages at launch on Android

In the default `Auto` mode, an `Activity` that started before activation doesn't trigger a request, so Google Play messages don't appear at launch. To show them at launch, call `Adapty.ShowStoreMessages` once after `Adapty.Activate` completes, on Android only:

```csharp showLineNumbers title="C#"
Adapty.Activate(builder.Build(), (error) => {
    if (error != null) {
        // handle the error
        return;
    }

#if UNITY_ANDROID
    Adapty.ShowStoreMessages((showError) => {
        // handle the error
    });
#endif
});
```

Don't make this call on iOS: in `Auto` mode, it has nothing to show, and on iOS 15 it fails.

### Show only some message types

To show only some of the pending App Store messages, pass the types as the first argument. The other messages stay pending:

```csharp showLineNumbers title="C#"
var iosFilter = new List<AdaptyStoreMessageType> {
    AdaptyStoreMessageType.BillingIssue,
    AdaptyStoreMessageType.PriceIncreaseConsent,
};

Adapty.ShowStoreMessages(iosFilter, (error) => {
    // handle the error
});
```

Without a filter, or with `null`, the SDK shows all pending messages, including types it doesn't recognize. An empty list shows none. Android ignores the filter and requests all Google Play messages.

### Errors

`Adapty.ShowStoreMessages` can fail with an [`AdaptyError`](error-handling-on-flutter-react-native-unity) with one of these codes. All of them except `WrongParam` occur on iOS only:

| Code | Name | Cause |
|:-----|:-----|:------|
| 2006 | `DecodingFailed` | The device runs iOS 15 or earlier. Call the method only on iOS 16 and later. |
| 3201 | `OperationInProgress` | Another `Adapty.ShowStoreMessages` call is still showing messages, and this call has messages to show. Wait for the first call to finish, then try again. |
| 3202 | `ResolverFailure` | The SDK found no foreground-active window scene to show the messages in. Call the method again when your app is in the foreground. |
| 3001 | `WrongParam` | The filter list contains `null`. The SDK rejects the call before it reaches the store. |