Fixes & improvements

Author: eandreeva-twr

src/assets/shared/img/new-locale-flow.webp

@@ -102,10 +102,7 @@ Next, [create a placement](create-placement) and add the flow to it. Then [rende
 
 ## Add a locale
 
-To localize your flow, click **Add locale** above the editor and fill in:
-
-- **Code**: The locale code, for example `en`, `fr`, or `de`.
-- **Name**: The display name, for example English or French.
+To localize your flow, click **Add locale** above the editor and select locales.
 
 Adapty adds a new column to the editor for that locale. Edit each column independently — at runtime, the SDK returns the `AdaptyRemoteConfig` entry whose `locale` matches the user's selection.
 

src/assets/shared/img/offer-flow.webp

@@ -12,7 +12,7 @@ Finish setting up your flow in the default locale before adding other languages.
 
 ## Add and set up localization
 
-1. In the left panel, click <Inline id="localizations.svg" alt="Localizations" />. Then, click **Add locale**. Enter the locale code (e.g., `fr`) and name (e.g., `French`), then confirm. Repeat for each locale you want to add.
+1. In the left panel, click <Inline id="localizations.svg" alt="Localizations" />. Then, click **Add locale**. Select the languages to add.
 
 <ZoomImage id="new-locale-flow.webp" width="500px" alt="Add locale dialog" />
 
@@ -64,9 +64,9 @@ Example:
 
 ```
 Screen	Element	Property	en	fr	es
-Welcome	title	content	Turn words into art	Transformez les mots en art	
-Welcome	subtitle	content	Create stunning images in seconds with AI	Créez des images en quelques secondes	
-Quiz	quiz-title	content	What will you create?		
+Welcome	title	content	Turn words into art	Transformez les mots en art
+Welcome	subtitle	content	Create stunning images in seconds with AI	Créez des images en quelques secondes
+Quiz	quiz-title	content	What will you create?
 ```
 
 :::note

src/content/docs/guides/flow-builder/customize-flow-with-remote-config.mdx

@@ -111,6 +111,4 @@ Adapty automatically applies win-back offers if users are eligible. Set up your
 After you've added offers, continue the setup:
 - If you also have **Google Play apps**, set up [Google Play offers](google-play-offers).
 - If you have **promotional or win-back offers**, [add them to Adapty](create-offer).
-- If you only have **introductory offers** and no promotional or win-back offers, you're all set. These sections may still be useful:
-  - [Working with offers in the Adapty Paywall Builder](create-offer#paywall-builder)
-  - [How Adapty works with offers](create-offer#how-adapty-works-with-offers)
+- If you only have **introductory offers** and no promotional or win-back offers, you're all set. The [How Adapty works with offers](create-offer#how-adapty-works-with-offers) section may still be useful.

src/content/docs/version-3.0/add-paywall-locale-in-adapty-paywall-builder.mdx

@@ -13,7 +13,7 @@ Adapty allows you to offer trials or discounts to new, existing, or churned subs
 After you have set them up in App Store Connect or Google Play Console, you need to add them to Adapty in two steps:
 
 1. [Add offers to products in Adapty using the offer IDs from stores.](#1-create-offer)
-2. [Add offers to paywalls so they can be applied.](#2-add-offer-to-paywall)
+2. [Display the offer in a flow or paywall.](#2-display-offer)
 
 :::warning
 Introductory offers (App Store) are applied automatically if the user is eligible. Do not add them to products in Adapty.
@@ -63,34 +63,34 @@ If the **App Store Offer ID** or **Play Store Offer ID** field is not active, sw
 6. (optional) Add more offers if needed by clicking **Add offer**.
 7. Click **Save** to add the offers to the product.
 
-## 2. Add offer to paywall
+## 2. Display offer
 
-:::info
-You can't add offers to paywalls in the **live** status. If you want to add an offer to an existing paywall, [duplicate](duplicate-paywalls) it and configure products in a new paywall.
-:::
+Once an offer is attached to a product, surface it where users see that product — in a flow or in a paywall.
 
-To make an offer visible and selectable within a [paywall](paywalls) for your app's users, follow these steps:
+### Add offer to flow
 
-1. When creating or editing a paywall, in the **General** tab, add a product to which you've just added the offer.
-2. Choose an offer you [created earlier](create-offer) for this product from the **Offer** list. The list is available only for the products that have offers.
-3. If needed, add more products and offers, but you can add only one offer for each product.
+In the [Flow Builder](adapty-flow-builder), an offer is attached to a product on a Products element. First add the product element and assign products to it — see [Set up purchases](paywall-product-block).
 
-<ZoomImage id="offer-paywall.webp" />
+To attach an offer:
+
+1. On the canvas, select the product card that should show the offer.
+2. In the right panel, under **Product**, select the product, then pick the offer from the **Select offer (optional)** dropdown.
 
-### Paywall builder
+<ZoomImage id="offer-flow.webp" width="500px" />
+
+### Add offer to paywall
 
 :::info
-Paywalls created with the Adapty Paywall Builder will display only the first phase of a [multi-phase Google subscription offer](https://support.google.com/googleplay/android-developer/answer/12154973). However, rest assured that when a user purchases the product, all offer phases will be applied as configured in Google Play.
+You can't add offers to paywalls in the **live** status. If you want to add an offer to an existing paywall, [duplicate](duplicate-paywalls) it and configure products in a new paywall.
 :::
 
-When you create a paywall in the Adapty Paywall Builder, you have some more customization options for trials:
-- **Toggle**: In **Products**, set **Product grouping** to **Toggle** and add product-offer combinations for each toggle state. The most common use case is to include a product without an offer (e.g., direct purchase without a free trial) and a different product with an offer attached.
-
-<ZoomImage id="trial-toggle.webp" />
+To make an offer visible and selectable within a [paywall](paywalls) for your app's users, follow these steps:
 
-- **Dynamic text**: You can make the purchase button text change depending on the offer available to the user seeing the paywall. You can set different texts for **Default**, **Free trial**, **Pay as you go**, and **Pay up front**.
+1. When creating or editing a paywall, in the **General** tab, add a product to which you've just added the offer.
+2. Choose an offer you created earlier for this product from the **Offer** list. The list is available only for the products that have offers.
+3. If needed, add more products and offers, but you can add only one offer for each product.
 
-<ZoomImage id="button-text.webp" />
+<ZoomImage id="offer-paywall.webp" />
 
 ## How Adapty works with offers
 

src/content/docs/version-3.0/app-store-offers.mdx

@@ -19,7 +19,7 @@ To process offers, Adapty needs the following setup:
    - [App Store](app-store-offers)
    - [Google Play](google-play-offers)
 2. For App Store: [upload your In-App Purchase Key from App Store Connect to Adapty](app-store-connection-configuration#step-4-for-trials-and-special-offers--set-up-promotional-offers).
-3. [Add the offers to Adapty and assign them to a paywall](create-offer).
+3. [Add the offers to Adapty and display them in a flow or paywall](create-offer).
 
 :::note
 Introductory offers on iOS are applied automatically if the user is eligible. Do not add them to Adapty.

src/content/docs/version-3.0/create-offer.mdx

@@ -10,16 +10,14 @@ import Contentid from '@site/src/components/InlineTooltip';
 import InlineTooltip from '@site/src/components/InlineTooltip';
 import CustomDocCardList from '@site/src/components/CustomDocCardList';
 
-<CustomDocCardList ids={['create-paywall', 'adapty-paywall-builder', 'paywall-metrics']} />
+<CustomDocCardList ids={['create-paywall', 'paywall-metrics']} />
 
 <ZoomImage id="paywall.webp" width="700px" />
 
-In Adapty, **paywalls are the only way to show and sell products in your app**. This way, you can easily track how different product sets perform for different user groups and control how each product is displayed.
+In Adapty, a **paywall** is a remotely configured set of products you sell in your app. Managing products through a paywall lets you track how different product sets perform for different user groups and control how each product is displayed.
 
-Adapty offers you two main ways to design a paywall:
-- **Use the Adapty Paywall Builder**: You [create a complete, purchase-ready paywall in the no-code builder](quickstart-paywalls). Adapty automatically renders it and handles all the complex purchase flow, receipt validation, and subscription management behind the scenes.
-- **Design your paywall manually**: When designing a paywall manually, you have the following options:
-   - [Use a remote config](customize-paywall-with-remote-config): Instead of hardcoding values in your app code, you can manage your paywall elements (like text and media) dynamically from the dashboard without redeploying your app.
-   - <InlineTooltip tooltip="Delegate handling purchases to Adapty">[iOS](making-purchases), [Android](android-making-purchases), [React Native](react-native-making-purchases), [Flutter](flutter-making-purchases), and [Unity](unity-making-purchases)</InlineTooltip>: Integrating with the store APIs on your own is very time-consuming. Instead of doing it, you can use just one method in the Adapty SDK that handles all the complicated purchase logic.
+You render a paywall in your own app code. Adapty provides two features to help:
+- **Remote config**: [Manage paywall elements](customize-paywall-with-remote-config) like text and media dynamically from the dashboard, without redeploying your app.
+- **SDK purchase methods**: Instead of integrating with store APIs yourself, use one Adapty SDK method that handles the purchase logic — see <InlineTooltip tooltip="Delegate handling purchases to Adapty">[iOS](making-purchases), [Android](android-making-purchases), [React Native](react-native-making-purchases), [Flutter](flutter-making-purchases), and [Unity](unity-making-purchases)</InlineTooltip>.
 
-<CustomDocCardList ids={['fallback-paywalls', 'paywall-localization', 'customize-paywall-with-remote-config', 'web-paywall']} />
+<CustomDocCardList ids={['fallback-paywalls', 'paywall-localization', 'customize-paywall-with-remote-config', 'web-paywall']} />

src/content/docs/version-3.0/offers.mdx

@@ -16,16 +16,21 @@ import 'react-medium-image-zoom/dist/styles.css';
 To proceed with this guide, make sure you've completed the [store integration](integrate-payments) and created at least one product as described in the previous [guide on adding products](quickstart-products).
 :::
 
-Now that you have products, you need a way to show them to users. Adapty gives you two options:
+Now that you have products, you need a way to show them to users. Adapty gives you three options:
 
 - **Flow Builder (recommended)**: No-code visual editor for the full purchase journey. The Adapty SDK renders the result natively, so there's no UI code to write.
 - **Manual paywall**: You create a paywall, attach products to it, and render the UI yourself in app code.
+- **Adapty Paywall Builder (Legacy)**: No-code paywall editor.
 
 Both options end the same way: you attach what you built to a [placement](placements). The placement is what your app calls at runtime to fetch the right content for the right user.
 
 <Tabs groupId="purchase-setup" queryString>
 <TabItem value="flow-builder" label="Use the Flow Builder" default>
 
+:::important
+The Flow Builder currently supports iOS SDK v4 and later only. Support for other platforms is coming soon.
+:::
+
 A flow is one or more screens with products embedded directly. You design it in the [Flow Builder](adapty-flow-builder) — no code required.
 
 The Adapty SDK renders flows natively on each platform. Your app calls `getFlow`, and the SDK presents the screens, handles purchases, and reports events. No separate UI code, no paywall to maintain alongside.
@@ -155,6 +160,41 @@ In your app code you hardcode only the placement IDs. Everything else — which
 Adapty lets you show different paywalls to various user groups and analyze performance. Learn more about [audiences](audience) and [A/B tests](ab-tests).
 :::
 
+</TabItem>
+<TabItem value="paywall-builder" label="Adapty Paywall Builder (Legacy)">
+
+A paywall built in the [Paywall Builder](adapty-paywall-builder) is a no-code screen with products embedded directly. The Adapty SDK renders it natively, so there's no UI code to write.
+
+:::warning
+The Paywall Builder is fully functional, but Adapty is no longer adding features or shipping updates for it. For new projects, use the [Flow Builder](adapty-flow-builder) instead.
+:::
+
+### 1. Build the paywall
+
+1. Go to [**Paywalls**](https://app.adapty.io/paywalls) in the Adapty main menu.
+2. Click **Create paywall**.
+3. Enter a **Paywall name**. This is an internal identifier in the Adapty Dashboard.
+4. Click **Add product** and pick the products to display on the paywall.
+5. Open the **Builder & Generator** tab. Create a paywall from a template or generate it using AI.
+6. Switch on the **Show on device** toggle so the SDK can render it.
+
+<ZoomImage id="design-paywall.gif" />
+
+### 2. Add the paywall to a placement
+
+Create a <InlineTooltip tooltip="placement">A placement is a specific point in your app where you show a flow, paywall, onboarding, or A/B test. Placements let you target specific [audiences](audience) with your content. Learn more about [placements](placements).</InlineTooltip> so your app can request the paywall at runtime.
+
+1. Go to [**Placements**](https://app.adapty.io/placements) in the Adapty main menu and switch to the **Paywalls** tab.
+2. Click **Create placement**.
+3. Enter a **Placement name** (e.g., `main` or `onboarding`). This is an internal identifier in the Adapty Dashboard.
+4. Enter a **Placement ID**. You'll use this ID in the Adapty SDK to load the placement's paywall.
+5. Click **Run paywall** and choose the paywall you built.
+6. Click **Save & publish**.
+
+<ZoomImage id="add-placement.gif" />
+
+In your app code you hardcode only the placement IDs. Everything else — which paywall runs, which products it sells, how it looks — is configured in the Adapty Dashboard and can be changed anytime without an app update.
+
 </TabItem>
 </Tabs>