Skip to main content

​
Overview

Promotional offers let you give existing or lapsed subscribers a discounted or free period when they accept an Encore retention offer. The offer is created in App Store Connect and linked through your Encore dashboard. When Encore presents a retention offer, the PurchaseRequest includes the promoOfferId so your purchase handler can apply it.
Promotional offers differ from introductory offers. Introductory offers apply automatically to new subscribers, while promotional offers are targeted — your app decides when and to whom they’re shown. Encore handles this targeting for you.

​
Prerequisites

  • An auto-renewable subscription product configured in Encore (see Add 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

1

Open your subscription

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

Add a promotional offer

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

Configure the offer

Fill in the following fields:
For retention offers, Free for 1–3 months tends to perform best. This gives churning users a compelling reason to stay without requiring immediate payment.
4

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 server-side signature verification. If you’re using StoreKit directly (not a third-party manager), Encore signs offers on your behalf using a separate In-App Purchase key.
This is a different key from the one you uploaded to connect your store catalog. The App Store Connect API key you uploaded during onboarding (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 inventory-sync key never signs offers, and the In-App Purchase key is only needed when you sign offers with StoreKit directly.
1

Open the keys page

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

Generate a key

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

Copy the Key ID

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

Download the .p8 file

Click Download to save the .p8 private key file. You can only download this file once — 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, Qonversion), they handle offer signing through their own SDKs. You do not need to upload the .p8 key to Encore — but you still need the promotional offer created in App Store Connect.
  1. Go to your app in the Encore Dashboard
  2. Navigate to Entitlements → Promotional Offer Setup
  3. Enter the Promotional Offer ID (the Promotional Offer Identifier from Step 1)
  4. If using StoreKit directly, also provide your Key ID and upload the .p8 file
  5. Select your Subscription Manager and follow the integration instructions shown

​
Naming Convention

Use a consistent naming pattern for your promotional offer IDs:

​
Handling the Offer in Code

Once the promotional offer is created and linked, Encore includes the promoOfferId in the PurchaseRequest when presenting retention offers. How you apply it depends on your subscription manager — see Promotional Offer Handling for per-manager code examples.

​
Next Steps