Create a Promotional Offer

Overview

Promotional offers let you give existing or lapsed subscribers a discounted or free period when they accept an Encore offer at a churn moment. You create the offer in App Store Connect, link it through your Encore dashboard, and apply it in your purchase controller when it runs the purchase.

A promotional offer is a targeted discount or free period you extend to a specific existing or lapsed subscriber at a moment you choose.

Prerequisites

An auto-renewable subscription product configured in Encore (see App Store Subscription Product: connect your App Store Connect catalog and pick the product)
Access to App Store Connect with the Admin or App Manager role

Step 1: Create the promotional offer

Open your subscription

Go to App Store Connect → Apps → your app → Subscriptions. Select the subscription product you want to add a promotional offer to.

Add a promotional offer

Scroll down to the Subscription Prices section and click the ”+” button. Then click Create Promotional Offer

Configure the offer

Fill in the following fields:

Field	Description	Example
Reference Name	Internal label (not shown to users)	`Encore 3 Month Free`
Promotional Offer Identifier	Unique identifier you’ll enter in the Encore dashboard	`com.yourapp.promo.3m.free`
Offer Type	Free, Pay As You Go, or Pay Up Front	`Free`
Duration	How long the offer lasts	`2 Months`

For churn moments, a Free period of a few months tends to perform best. This gives a churning user a compelling reason to stay without requiring immediate payment.

Save

Click Create to save the promotional offer. The Promotional Offer Identifier you entered above is the value you’ll enter as the Promotional Offer ID in the Encore dashboard.

Step 2: Generate an In-App Purchase key

Promotional offers require a server-generated signature. If you’re using StoreKit directly (not a third-party manager), the signature is generated with a separate In-App Purchase key, which you upload to Encore.

This is a different key from the one you uploaded to connect your store catalog. The App Store Connect API key from App Store Subscription Product (Key ID + Issuer ID + .p8, App Manager role) is read-only for product setup and pricing display: Encore uses it to sync your subscription catalog and show your products. It does not sign promotional offers.Promotional-offer signing uses a dedicated In-App Purchase key, generated on a different App Store Connect page (below) and uploaded separately under Entitlements → Promotional Offer Setup. Keep the two distinct: the catalog-sync key never signs offers, and the In-App Purchase key is only needed when you sign offers with StoreKit directly.

Open the keys page

Go to App Store Connect → Users and Access → Integrations → In-App Purchase.

Generate a key

Click “Generate In-App Purchase Key” and give it a descriptive name (e.g., Encore Signing Key).

Copy the Key ID

Copy the Key ID shown in the table (e.g., WHJ3V7RXNW). You’ll need this in the Encore dashboard.

Download the .p8 file

Click Download to save the .p8 private key file. You can only download this file once, so store it securely.

The .p8 key file can only be downloaded once. If you lose it, you’ll need to generate a new key.

If you use a third-party subscription manager (RevenueCat, Adapty), it handles offer signing through its own SDK. You do not need to upload the .p8 key to Encore, but you still need the promotional offer created in App Store Connect.

Step 3: Link in the Encore Dashboard

Go to your app in the Encore Dashboard
Navigate to Entitlements → Promotional Offer Setup
Enter the Promotional Offer ID (the Promotional Offer Identifier from Step 1)
If using StoreKit directly, also provide your Key ID and upload the .p8 file
Select your Subscription Manager and follow the integration instructions shown

Naming convention

Use a consistent naming pattern for your promotional offer IDs:

{bundle_id}.promo.{duration}.{type}

Example	Meaning
`com.yourapp.promo.3m.free`	3 months free
`com.yourapp.promo.1m.free`	1 month free
`com.yourapp.promo.6m.payasyougo`	6 months at a reduced price

Handling the offer in code

PurchaseRequest.promoOfferId is reserved and is always nil on iOS SDK 2.0, so Encore does not drive promotional-offer selection. Your EncorePurchaseController decides when a promotional offer applies and signs it with your own billing code. How you apply it depends on your subscription manager:

Encore-driven promotional offers are not yet available in the iOS SDK. Until they are, keep the promotional offer id in your own code.

StoreKit
RevenueCat
Adapty

With StoreKit 2, applying a promotional offer requires a server-generated signature: sign the offer with the In-App Purchase key from Step 2, then pass the signed offer to product.purchase(options:) via Product.PurchaseOption.promotionalOffer. See Apple’s Implementing promotional offers for the signing flow.

final class AppPurchases: EncorePurchaseController {
    func purchase(_ request: PurchaseRequest) async throws -> EncorePurchaseResult {
        guard let product = try await Product.products(for: [request.productId]).first else {
            throw PurchaseError.notFound
        }
        // Your own code decides when a promotional offer applies and fetches
        // the signature for promoOfferId from your signing endpoint.
        let options: Set<Product.PurchaseOption> = [
            .promotionalOffer(
                offerID: promoOfferId,
                keyID: keyID, nonce: nonce, signature: signature, timestamp: timestamp
            )
        ]
        switch try await product.purchase(options: options) {
        case .success(let verification):
            if case .verified(let transaction) = verification { await transaction.finish() }
            return .purchased
        case .userCancelled: return .cancelled
        case .pending: return .pending
        @unknown default: return .cancelled
        }
    }
}

Manually check for the promotional offer, sign it through RevenueCat, and fall back to a standard purchase if the user isn’t eligible.

final class AppPurchases: EncorePurchaseController {
    func purchase(_ request: PurchaseRequest) async throws -> EncorePurchaseResult {
        guard let product = try await Purchases.shared.products([request.productId]).first else {
            throw PurchaseError.notFound
        }
        // promoOfferId is your own value; Encore does not supply it.
        if let promoDiscount = product.discounts.first(where: { $0.offerIdentifier == promoOfferId }) {
            do {
                let offer = try await Purchases.shared.promotionalOffer(
                    forProductDiscount: promoDiscount, product: product
                )
                let result = try await Purchases.shared.purchase(product: product, promotionalOffer: offer)
                return result.userCancelled ? .cancelled : .purchased
            } catch {
                // Promo failed (ineligible, network error, etc.): fall back to standard purchase
                let result = try await Purchases.shared.purchase(product: product)
                return result.userCancelled ? .cancelled : .purchased
            }
        } else {
            let result = try await Purchases.shared.purchase(product: product)
            return result.userCancelled ? .cancelled : .purchased
        }
    }
}

Your local StoreKit configuration file must be synced with App Store Connect. Promotional offers will not work if it is out of sync.

Adapty automatically presents the promotional offer if the user is eligible (when configured correctly in the Adapty dashboard). Falls back to a standard purchase with an introductory offer.

final class AppPurchases: EncorePurchaseController {
    func purchase(_ request: PurchaseRequest) async throws -> EncorePurchaseResult {
        let paywall = try await Adapty.getPaywall(placementId: "YOUR_PAYWALL_PLACEMENT_ID")
        let products = try await Adapty.getPaywallProducts(paywall: paywall)
        guard let product = products.first(where: {
            $0.vendorProductId == request.productId
        }) else {
            throw PurchaseError.notFound
        }
        let result = try await Adapty.makePurchase(product: product)
        return result.isPurchaseCancelled ? .cancelled : .purchased
    }
}

Adapty does not fall back to StoreKit: products and offers must exist in Adapty. Sync products in the Adapty dashboard before use, and configure the promotional offer there (it does not sync from App Store Connect automatically).

See EncorePurchaseController for the full controller contract.

Next steps

App Store Subscription Product: the base subscription product the offer discounts.
Reduce Churn: the use case these offers serve.

iOS

Android

Web

Bridges

Create a Promotional Offer

Overview

Prerequisites

Step 1: Create the promotional offer

Step 2: Generate an In-App Purchase key

Step 3: Link in the Encore Dashboard

Naming convention

Handling the offer in code

Next steps

​Overview

​Prerequisites

​Step 1: Create the promotional offer

​Step 2: Generate an In-App Purchase key

​Step 3: Link in the Encore Dashboard

​Naming convention

​Handling the offer in code

​Next steps

Overview

Prerequisites

Step 1: Create the promotional offer

Step 2: Generate an In-App Purchase key

Step 3: Link in the Encore Dashboard

Naming convention

Handling the offer in code

Next steps