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:

  1. Read the setup status.
  2. Read the realtime URL, and request access from Apple with it.
  3. Configure the realtime URL for sandbox.
  4. Run the performance test, and read the setup status until the test has passed.
  5. Configure the realtime URL for production.
  6. Create the default messages, then the promo messages.
  7. 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:

FieldValues
credentialspresent or missing: whether the app has the App Store keys that Retention Messaging uses.
registration_statusregistered or not_registered: whether Apple gave the app access to the Retention Messaging API.
sandbox.realtime_url_status, production.realtime_url_statusnot_configured, configured_to_other_url, or configured_to_adapty: where Apple sends its requests in each environment.
sandbox.performance_test_statusnot_started, running, passed, or failed.
Note

Some reads also update Adapty, as the dashboard does:

  • While the performance test runs, setup-status asks Apple for the result of the test and saves it. realtime-url configure makes 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 that messages update makes 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 to live right 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 answer y at the Apply? [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:

FieldDashboard columnValue
shownShownCount
retainedRetained usersCount
saved_usersSaved usersCount
retention_rateRetention ratePercent, one decimal place. 0.0 while no view has an outcome.
save_rateSave ratePercent, one decimal place. 0.0 while no view is older than 24 hours.
saved_revenueSaved revenueUSD 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 the en-US source, up to 66 and 144 characters.
  • type: The message type, default or promo. 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_image shows the title above the image. above_body shows 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 in store_id. A default message has no association. A promo message needs at least one product, and each product needs an incentive in association: {"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: all promo_offer or all plan_switch.
  • bullet_points: Up to five, for a default message only. Each has text (1–66 characters), an optional alt_text, and image_path: the path to its PNG icon, relative to the folder of the JSON file. The CLI refuses image_index.
  • localizations: One entry for each locale other than en-US, with locale, title, body, and one bullet_points text 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

FileRequirements
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

Warning

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, with title, body, and the bullet point texts of the locale in bullet_texts, by bullet_id. A locale that the message doesn’t have is added, and it needs title, body, and a text for each bullet point.
  • Bullet points: To change a bullet point, name it by its bullet_id from messages get, with text, alt_text, or image_path for a new icon. A new bullet point has no bullet_id. It needs image_path, the en-US text, and a text in texts for 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 new association. To stop offering an incentive on a product, remove the product with remove_products. A product that you add to a promo message needs an association.
  • Removals: Use the remove fields: remove_localizations (locale codes), remove_bullet_points (bullet IDs), remove_products (App Store product IDs), and remove_image: true or --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 an inactive message to in_review. Apple reviews again only the locales it hasn’t approved. After Apple approves the message, subscribers see it again.
  • deactivate: Moves a live message to inactive. 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 configure
  • messages create
  • messages update
  • messages set-status

How it asks depends on how the command runs:

How the command runsWhat happens
In a terminal, without --yes and without --jsonThe 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 notThe CLI sends the request without asking, even in production.
Without --yes, with --json, in a pipe, or with no terminalThe 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 codeCauseWhat to do
1You answered something other than y at the prompt. Nothing was sent.Run the command again if you meant to.
2The 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.
3You 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.
4Adapty 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.
5The 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.
6A 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.
130You pressed Ctrl+C at the prompt. Nothing was sent.—

Messages from Adapty

With --json, the error gives the error_code:

error_codeCauseWhat to do
app_store_credentials_missingThe app has no App Store keys in Adapty.Complete the App Store setup.
app_store_connect_credentials_missingplan-switches suggest needs the App Store Connect API key.Add the App Store Connect API key.
realtime_url_unavailableThe app has no App Store server notifications setup in Adapty.Complete the App Store setup.
apple_rm_api_access_deniedApple hasn’t given the app access to the Retention Messaging API.Request access from Apple.
performance_test_requiredYou configured production before the performance test passed.Run the performance test first.
performance_test_already_runningA performance test runs.Wait, then read the setup status again.
active_sandbox_transaction_missingNo active sandbox subscription.Purchase your longest-duration product in sandbox, then start the test again.
performance_test_request_rejectedApple refused to start the test.Make a new sandbox purchase, then start the test again.
retention_product_claimedAnother message of the same type has the product.Pick another product, or deactivate the other message.
retention_default_message_missingA promo message has a product with no default message.Create or activate a default message for the product first.
retention_dependent_promo_messagesA 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_invalidA 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_immutableThe change gives a promo message a different incentive type.Create a new message.
retention_message_invalid_status_transitionactivate 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_foundThe 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 list for the same environment with --search "<name>" --page-size 100. The error prints the exact name on its own line (message_name in --json). Read every page up to meta.pagination.pages, and open each candidate with messages 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

FlagRequiredDescription
--modeYessandbox or production.
--replace-other-urlNoApprove the replacement of a different URL in Apple.
--yes, -yNoConfigure 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

FlagRequiredDescription
--modeYessandbox or production.
--searchNoPart of the name, any case, or the exact message ID.
--typeNodefault or promo.
--stateNoin_review, live, rejected, or inactive.
--orderingNoname, type, state, products_count, or started_at. Add - before the field for the reverse order. Default: -started_at.
--pageNoPage number. Default: 1.
--page-sizeNoMessages 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

FlagRequiredDescription
--modeYessandbox or production.
--fileYesThe JSON file of the message, or - to read it from standard input. See Create a message.
--imageNoThe PNG image of a default message.
--yes, -yNoCreate without asking. Required with --json or in a pipe.

retention-messaging messages update

Takes the message ID as its argument.

FlagRequiredDescription
--name, --title, --body, --alt-textNoNew value of the field.
--imageNoNew PNG image.
--remove-imageNoRemove the image.
--fileNoThe changes file, or - to read it from standard input. See Change a message.
--yes, -yNoChange without asking. Required with --json or in a pipe.

retention-messaging messages set-status

Takes the message ID as its argument.

FlagRequiredDescription
--actionYesactivate or deactivate.
--yes, -yNoChange the status without asking. Required with --json or in a pipe.

retention-messaging products suggest

FlagRequiredDescription
--modeYessandbox or production.
--typeYesdefault or promo: the type of the message.
--searchNoPart of the product title, any case.
--message-idNoThe ID of the message that you change.
--limitNoProducts to return, up to 100. Default: 10.

retention-messaging promo-offers suggest

Takes the product ID from products suggest as its argument.

FlagRequiredDescription
--searchNoPart of the offer title, any case.
--limitNoOffers to return, up to 100. Default: 10.

retention-messaging plan-switches suggest

Takes the product ID from products suggest as its argument.

FlagRequiredDescription
--searchNoPart of the plan title, any case.
--limitNoPlans 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 sandbox and in production. 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_create creates a message without an image or bullet points. To add them, run messages update from the CLI, or use the dashboard.

What’s next