Manage Retention Messaging from the CLI
The Adapty CLI sets up Apple Retention Messaging, the message that subscribers see on the Cancel Subscription screen, from the terminal, under the adapty retention-messaging topic. You can read the setup status of an app, connect Apple to the Adapty realtime URL that answers Apple’s requests for a message, run Apple’s performance test, create and change retention messages, activate and deactivate them, and read the metrics of each message.
Use it to let an AI agent set up Retention Messaging for you, to script messages across several apps, or to read the message metrics without opening the dashboard. The commands do the same actions as the Retention Messaging page of the dashboard, and the dashboard shows the same messages.
Before you start
The retention-messaging topic uses the same installation and login as the rest of the CLI. If you have not set that up, follow steps 1 and 2 of the quickstart guide. To see whether your CLI has the topic, run:
adapty retention-messaging --help
Every command takes the app’s UUID in --app. To find it, run:
adapty apps list
What your app needs for each step:
- Read the setup status: Nothing. Works for any app.
- Read the realtime URL: A complete App Store setup in Adapty. You send this URL to Apple when you request access.
- Configure the realtime URL and run the performance test: Also the In-App Purchase key, and access to the Retention Messaging API, which you request from Apple. Apple’s review can take up to a month, so request access early.
- Show messages to subscribers: Access from Apple, the realtime URL set to Adapty, at least one product, and Apple’s approval of each message.
Retention messages exist in two Apple environments: sandbox and production. The --mode flag selects the environment. Each environment has its own messages, as the Sandbox mode toggle of the dashboard shows.
To set up Retention Messaging from start to finish:
- Read the setup status.
- Read the realtime URL, and request access from Apple with it.
- Configure the realtime URL for
sandbox. - Run the performance test, and read the setup status until the test has passed.
- Configure the realtime URL for
production. - Create the default messages, then the promo messages.
- List the messages to follow Apple’s review.
Read the setup status
adapty retention-messaging setup-status --app <app-id>
The status shows the same setup steps as the dashboard:
| Field | Values |
|---|---|
credentials | present or missing: whether the app has the App Store keys that Retention Messaging uses. |
registration_status | registered or not_registered: whether Apple gave the app access to the Retention Messaging API. |
sandbox.realtime_url_status, production.realtime_url_status | not_configured, configured_to_other_url, or configured_to_adapty: where Apple sends its requests in each environment. |
sandbox.performance_test_status | not_started, running, passed, or failed. |
Some reads also update Adapty, as the dashboard does:
- While the performance test runs,
setup-statusasks Apple for the result of the test and saves it.realtime-url configuremakes the same read before it asks for approval, so it saves the result even if you then decline. messages list,messages get, and the read thatmessages updatemakes before it writes ask Apple about the review of each message and save the new state. If Apple has approved a message, the read moves it toliveright away. Adapty also checks Apple’s review on its own, so an approved message goes live without a read too.
Connect the realtime URL
Apple sends a request to a realtime URL when a subscriber opens the Cancel Subscription screen. Adapty answers this request with your message. To read the Adapty URL, run:
adapty retention-messaging realtime-url get --app <app-id>
The same URL serves sandbox and production. You give this URL to Apple when you request access.
To set the Adapty URL in Apple for one environment, run:
adapty retention-messaging realtime-url configure --app <app-id> --mode sandbox
Configure sandbox first. Adapty refuses production until the performance test passes. When you configure sandbox, Adapty also creates a hidden test message for the performance test. This message isn’t in the message list.
If Apple sends the requests of this environment to a different server (configured_to_other_url), the Adapty URL replaces that server’s URL in Apple. From then on, that server gets no requests from the Cancel Subscription screen. The CLI shows a warning that names the environment. To approve the replacement:
- In a terminal, without
--json: Read the warning and answeryat theApply? [y/N]prompt. The prompt appears even when you pass--yes. - In a script, an agent, or with
--json: Pass--replace-other-url --yes. Without--replace-other-url, the CLI sends nothing and exits with code 6, even with--yes.
Run the performance test
Apple tests how fast Adapty answers before Adapty allows the production realtime URL. Before you start the test, configure the realtime URL for sandbox. Then purchase your longest-duration product with a sandbox account or through TestFlight, keep the subscription active, and start the test right after the purchase:
adapty retention-messaging performance-test start --app <app-id>
The test always runs in sandbox and can take up to an hour. To see the result, read the setup status again: sandbox.performance_test_status changes from running to passed or failed. While the status is running, don’t start the test again: Adapty refuses it. To learn why a test fails, see Pass the performance test.
When the test passes, connect production:
adapty retention-messaging realtime-url configure --app <app-id> --mode production
List and read messages
adapty retention-messaging messages list --app <app-id> --mode production --state live
--mode is required. The list shows each message with its name, type, state, number of products, start date, and these metrics for the whole life of the message:
| Field | Dashboard column | Value |
|---|---|---|
shown | Shown | Count |
retained | Retained users | Count |
saved_users | Saved users | Count |
retention_rate | Retention rate | Percent, one decimal place. 0.0 while no view has an outcome. |
save_rate | Save rate | Percent, one decimal place. 0.0 while no view is older than 24 hours. |
saved_revenue | Saved revenue | USD before Apple’s commission, two decimal places |
For how Adapty calculates each metric, see Track message performance.
A message is in one of these states: in_review, live, rejected, or inactive. For what each state means, see Message states.
To read one message with its texts, image, bullet points, products, and locales, run:
adapty retention-messaging messages get <message-id> --app <app-id>
The message has no environment field. Its texts and bullet points are the en-US source. Each other locale shows its own review state.
Create a message
A promo message needs a default message for the same product in the same environment. Create the default message first. You don’t have to wait for Apple’s review of it.
To find the product IDs, the promo offers, and the plan switches for the file, use the suggest commands. To create a message, put its content in a JSON file:
{
"name": "Annual default",
"type": "default",
"title": "Before you go",
"body": "Your plan keeps every feature you use today.",
"alt_text": "App icon on a purple background",
"header_position": "above_body",
"products": [
{ "store_id": "com.example.annual" }
],
"bullet_points": [
{ "image_path": "icons/sync.png", "text": "Sync on all your devices" },
{ "image_path": "icons/offline.png", "text": "Work offline" }
],
"localizations": [
{
"locale": "de-DE",
"title": "Bevor du gehst",
"body": "Dein Abo behält alle Funktionen, die du heute nutzt.",
"bullet_points": [
{ "text": "Auf allen Geräten synchronisieren" },
{ "text": "Offline arbeiten" }
]
}
]
}
Then run:
adapty retention-messaging messages create --app <app-id> --mode sandbox \
--file message.json --image header.png
The file takes these keys:
name,type,title,body: Required. The title and body are theen-USsource, up to 66 and 144 characters.type: The message type,defaultorpromo. You can’t change the type later.alt_text: The description of the image for screen readers, up to 150 characters.header_position: The position of the title in a default message with an image.above_imageshows the title above the image.above_bodyshows it below the image, above the body. You can’t change it later.products: The products whose subscribers see the message, by their App Store product ID instore_id. A default message has noassociation. A promo message needs at least one product, and each product needs an incentive inassociation:{"type": "promo_offer", "store_id": "<offer-id>"}or{"type": "plan_switch", "store_id": "<product-id>"}. All products of one promo message use the same incentive type: allpromo_offeror allplan_switch.bullet_points: Up to five, for a default message only. Each hastext(1–66 characters), an optionalalt_text, andimage_path: the path to its PNG icon, relative to the folder of the JSON file. The CLI refusesimage_index.localizations: One entry for each locale other thanen-US, withlocale,title,body, and onebullet_pointstext for each bullet point of the message, in the same order.
--image adds the image of a default message. A promo message has no image and no bullet points.
Before it asks for your approval, the CLI validates each image file. The CLI then asks for approval, as described in Confirmation in scripts and agents. Adapty sends the texts and images of the new message to Apple for review, and the message state is in_review.
If a create fails with a network error or a server error, don’t run it again. See If a create or a change gets no answer.
Image requirements
| File | Requirements |
|---|---|
Image (--image) | PNG, 3840 px wide and 160–2160 px tall, no transparency, up to 10 MB |
Bullet point icon (image_path) | PNG, 1024 × 1024 px, no transparency, up to 10 MB |
The CLI validates each file before it sends anything. A PNG with an alpha channel passes if every pixel is fully opaque. A damaged PNG fails with the must be a PNG error. If a file fails, the CLI sends nothing and exits with code 2. The error names the file and the rule, for example … must be 3840 px wide and 160–2160 px tall.
Change a message
A change to an inactive message activates it again, even a change of the name only. After Apple approves the message, subscribers see it.
messages update changes only what you name. Every locale, bullet point, icon, product, and the image that you don’t name stay as they are:
adapty retention-messaging messages update <message-id> --app <app-id> --title "Wait, there's more"
Change the name, title, body, and alt text, and the image, with flags: --name, --title, --body, --alt-text, --image, and --remove-image. Change locales, bullet points, and products with a changes file in --file. The changes file also takes name, title, body, alt_text, and remove_image. The CLI refuses a key that the changes file doesn’t know. This changes file works on the message from Create a message:
{
"localizations": [
{ "locale": "de-DE", "title": "Warte kurz", "bullet_texts": { "<bullet-id>": "Auf jedem Gerät synchronisieren" } }
],
"bullet_points": [
{ "bullet_id": "<bullet-id>", "text": "Sync on every device" },
{
"image_path": "icons/backup.png",
"text": "Daily backups",
"texts": { "de-DE": "Tägliche Backups" }
}
],
"remove_bullet_points": ["<other-bullet-id>"]
}
- Locales: Name each locale by its code in
locale, withtitle,body, and the bullet point texts of the locale inbullet_texts, bybullet_id. A locale that the message doesn’t have is added, and it needstitle,body, and a text for each bullet point. - Bullet points: To change a bullet point, name it by its
bullet_idfrommessages get, withtext,alt_text, orimage_pathfor a new icon. A new bullet point has nobullet_id. It needsimage_path, theen-UStext, and a text intextsfor each locale of the message. - Products: By their App Store product ID in
store_id. A product that the message doesn’t have is added. In a promo message, each product needs an incentive: to change it, pass a newassociation. To stop offering an incentive on a product, remove the product withremove_products. A product that you add to a promo message needs anassociation. - Removals: Use the remove fields:
remove_localizations(locale codes),remove_bullet_points(bullet IDs),remove_products(App Store product IDs), andremove_image: trueor--remove-image. A removed bullet point disappears from every locale. While a promo message uses a product, you can’t remove that product from its default message.
You can’t change the type, the header_position, or the incentive type of a promo message (promo_offer or plan_switch). To use a different one, create a new message.
The CLI validates your changes before it sends anything. If the input contradicts itself, changes nothing, or names or removes something that the message doesn’t have, the CLI sends nothing, exits with code 2, and the error names the problem. Give the locale texts of an existing bullet point in bullet_texts of the locale, not in texts.
The CLI asks for approval, reads the message, merges your changes into it, and sends the full message to Adapty. Every update sends the whole message to Apple for review, and the message state becomes in_review. If someone changes the message in the dashboard while messages update runs, the update overwrites that change.
Activate or deactivate a message
adapty retention-messaging messages set-status <message-id> --app <app-id> --action deactivate
activate: Moves aninactivemessage toin_review. Apple reviews again only the locales it hasn’t approved. After Apple approves the message, subscribers see it again.deactivate: Moves alivemessage toinactive. Subscribers no longer see it. Views that occurred stay in the metrics.
Adapty refuses activate for a message that isn’t inactive, and deactivate for a message that isn’t live. A message in in_review goes live when Apple approves it. To stop it, deactivate it after that. The CLI has no command to delete a message.
A product can have one default message and one promo message in each environment. Adapty refuses the activation in these cases:
- Another message of the same type was added to the product while this message was inactive.
- The message is a promo message, and one of its products has no default message in this environment.
While a promo message uses a product, Adapty refuses to deactivate the default message of that product. Deactivate the promo message, or remove the product from it, first.
Find products and offers
To find the products that you can add to a message, run:
adapty retention-messaging products suggest --app <app-id> --mode production --type default
When you change a message, pass its ID in --message-id, so that the products of this message don’t show as used. A product with a disabled_reason can’t be added:
used: Another message of the same type in this environment has the product.no_default_message: The product has no default message in this environment, so it can’t get a promo message.
A promo message links one incentive to each product. To find the incentives for a product, pass the product id from products suggest. To list the promotional offers of the product, run:
adapty retention-messaging promo-offers suggest <product-id> --app <app-id>
To list the plans that a subscriber can switch to, run:
adapty retention-messaging plan-switches suggest <product-id> --app <app-id>
plan-switches suggest needs the App Store Connect API key in the app settings. Put the store_id of the offer or the plan in the association of the product.
Confirmation in scripts and agents
These commands change what subscribers see on the Cancel Subscription screen. Each one prints its effect and asks for approval before it sends the change, in sandbox and in production:
realtime-url configuremessages createmessages updatemessages set-status
How it asks depends on how the command runs:
| How the command runs | What happens |
|---|---|
In a terminal, without --yes and without --json | The CLI prints the effect and asks Apply? [y/N]. If you answer y or yes, the CLI sends the request. For any other answer, the CLI exits with code 1 and sends nothing. |
With --yes, in a terminal or not | The CLI sends the request without asking, even in production. |
Without --yes, with --json, in a pipe, or with no terminal | The CLI sends nothing and exits with code 6. The error describes the effect. |
Replacing a different realtime URL in Apple has its own rules. See Connect the realtime URL.
So a script or an agent can read the effect of a command first: run it without --yes, read the effect in the output, and run it again with --yes only after someone approves that effect.
setup-status, realtime-url get, performance-test start, messages list, messages get, and the suggest commands run without asking.
Errors
| Exit code | Cause | What to do |
|---|---|---|
| 1 | You answered something other than y at the prompt. Nothing was sent. | Run the command again if you meant to. |
| 2 | The CLI refused the input before it sent the change: a flag, an image file, a conflict in the input, a locale without a text for each bullet point, or a removal of something that the retention message doesn’t have. | Fix what the error names. |
| 3 | You aren’t logged in, or Adapty refused access to the app. | Log in with adapty auth login, and find the app ID in adapty apps list. |
| 4 | Adapty refused the request. The error gives the reason, and --json gives the HTTP status and error_code. A server error (5xx) on a create or a change also gives code 4, and the result is unknown. | See Messages from Adapty. After a server error on a create or a change, see If a create or a change gets no answer. |
| 5 | The CLI couldn’t reach Adapty. | Make sure you are online. After a create or a change, see If a create or a change gets no answer. |
| 6 | A command that asks for approval ran without --yes and with no one to answer, or a realtime URL replacement ran without --replace-other-url. Nothing was sent. | Read the effect in the error, then run the command again with --yes, and with --replace-other-url for a replacement. |
| 130 | You pressed Ctrl+C at the prompt. Nothing was sent. | — |
Messages from Adapty
With --json, the error gives the error_code:
error_code | Cause | What to do |
|---|---|---|
app_store_credentials_missing | The app has no App Store keys in Adapty. | Complete the App Store setup. |
app_store_connect_credentials_missing | plan-switches suggest needs the App Store Connect API key. | Add the App Store Connect API key. |
realtime_url_unavailable | The app has no App Store server notifications setup in Adapty. | Complete the App Store setup. |
apple_rm_api_access_denied | Apple hasn’t given the app access to the Retention Messaging API. | Request access from Apple. |
performance_test_required | You configured production before the performance test passed. | Run the performance test first. |
performance_test_already_running | A performance test runs. | Wait, then read the setup status again. |
active_sandbox_transaction_missing | No active sandbox subscription. | Purchase your longest-duration product in sandbox, then start the test again. |
performance_test_request_rejected | Apple refused to start the test. | Make a new sandbox purchase, then start the test again. |
retention_product_claimed | Another message of the same type has the product. | Pick another product, or deactivate the other message. |
retention_default_message_missing | A promo message has a product with no default message. | Create or activate a default message for the product first. |
retention_dependent_promo_messages | A promo message uses a product that the change takes away from a default message. | Deactivate the promo message, or remove the product from it, first. |
retention_promo_association_invalid | A promo message has no product, a product without association, or both incentive types. | Give every product an association of the same type. |
retention_message_type_immutable | The change gives a promo message a different incentive type. | Create a new message. |
retention_message_invalid_status_transition | activate on a message that isn’t inactive, or deactivate on a message that isn’t live. | Read the state of the message with messages get. |
retention_message_not_found | The app has no message with this ID. | Take the ID from messages list. |
If a create or a change gets no answer
If the CLI gets no answer to a create or an update, because of a network error or a server error (exit code 4 or 5), it can’t tell whether Adapty saved the change. The CLI doesn’t send the request again. Don’t run the command again yourself either.
- After a create: Run
messages listfor the same environment with--search "<name>" --page-size 100. The error prints the exact name on its own line (message_namein--json). Read every page up tometa.pagination.pages, and open each candidate withmessages get. A second create can make a duplicate message and send it to Apple’s review. Create the message again only if no candidate is your message. - After an update: Run
messages get, and read the state and the content of the message.
Command reference
Every command takes --app, the app UUID from adapty apps list.
retention-messaging setup-status
Returns the setup status. Takes no other flags.
retention-messaging realtime-url get
Returns the Adapty realtime URL. Takes no other flags.
retention-messaging realtime-url configure
| Flag | Required | Description |
|---|---|---|
--mode | Yes | sandbox or production. |
--replace-other-url | No | Approve the replacement of a different URL in Apple. |
--yes, -y | No | Configure without asking. Required with --json or in a pipe. |
retention-messaging performance-test start
Starts Apple’s performance test in sandbox. Takes no other flags.
retention-messaging messages list
| Flag | Required | Description |
|---|---|---|
--mode | Yes | sandbox or production. |
--search | No | Part of the name, any case, or the exact message ID. |
--type | No | default or promo. |
--state | No | in_review, live, rejected, or inactive. |
--ordering | No | name, type, state, products_count, or started_at. Add - before the field for the reverse order. Default: -started_at. |
--page | No | Page number. Default: 1. |
--page-size | No | Messages per page, up to 100. Default: 20. |
retention-messaging messages get
Takes the message ID as its argument. Returns the full message.
retention-messaging messages create
| Flag | Required | Description |
|---|---|---|
--mode | Yes | sandbox or production. |
--file | Yes | The JSON file of the message, or - to read it from standard input. See Create a message. |
--image | No | The PNG image of a default message. |
--yes, -y | No | Create without asking. Required with --json or in a pipe. |
retention-messaging messages update
Takes the message ID as its argument.
| Flag | Required | Description |
|---|---|---|
--name, --title, --body, --alt-text | No | New value of the field. |
--image | No | New PNG image. |
--remove-image | No | Remove the image. |
--file | No | The changes file, or - to read it from standard input. See Change a message. |
--yes, -y | No | Change without asking. Required with --json or in a pipe. |
retention-messaging messages set-status
Takes the message ID as its argument.
| Flag | Required | Description |
|---|---|---|
--action | Yes | activate or deactivate. |
--yes, -y | No | Change the status without asking. Required with --json or in a pipe. |
retention-messaging products suggest
| Flag | Required | Description |
|---|---|---|
--mode | Yes | sandbox or production. |
--type | Yes | default or promo: the type of the message. |
--search | No | Part of the product title, any case. |
--message-id | No | The ID of the message that you change. |
--limit | No | Products to return, up to 100. Default: 10. |
retention-messaging promo-offers suggest
Takes the product ID from products suggest as its argument.
| Flag | Required | Description |
|---|---|---|
--search | No | Part of the offer title, any case. |
--limit | No | Offers to return, up to 100. Default: 10. |
retention-messaging plan-switches suggest
Takes the product ID from products suggest as its argument.
| Flag | Required | Description |
|---|---|---|
--search | No | Part of the plan title, any case. |
--limit | No | Plans to return, up to 100. Default: 10. |
Work from an AI assistant
The Adapty MCP server offers the same actions as retention_messaging_* tools, for example retention_messaging_messages_list for messages list. The tools take message_type in place of --type.
- Approval: The assistant asks before it configures the realtime URL, creates or changes a message, or changes its status, in
sandboxand inproduction. Before it replaces another server’s realtime URL, it asks a separate question. It also asks once in each conversation before its first setup status read, and once before its first message read, because these reads can update Adapty. - Images and bullet points: The MCP tools can’t add an image, a bullet point icon, or a new bullet point.
retention_messaging_messages_createcreates a message without an image or bullet points. To add them, runmessages updatefrom the CLI, or use the dashboard.
What’s next
- Agent skill for Retention Messaging — let your agent set up Retention Messaging and write your messages, with your yes before each change.
- Set up Retention Messaging — the same setup steps in the dashboard.
- Create a retention message — the message fields, locales, and states in the dashboard.
- Track message performance — what each metric means.