> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encorekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Promotional Offer

> Step-by-step guide to creating a promotional offer in App Store Connect for use with Encore retention flows.

## 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](https://dashboard.encorekit.com). When Encore presents a retention offer, the `PurchaseRequest` includes the `promoOfferId` so your purchase handler can apply it.

<Info>
  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.
</Info>

***

## Prerequisites

* An auto-renewable subscription product configured in Encore (see [Add Subscription Product](../quickstart/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

<Steps>
  <Step title="Open your subscription">
    Go to [App Store Connect](https://appstoreconnect.apple.com) → **Apps** → your app → **Subscriptions**. Select the subscription product you want to add a promotional offer to.
  </Step>

  <Step title="Add a promotional offer">
    Scroll down to the **Subscription Prices** section and click the **"+"** button. Then click **Create Promotional Offer**
  </Step>

  <Step title="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`                  |

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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>
</Steps>

***

## 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**.

<Warning>
  **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.
</Warning>

<Steps>
  <Step title="Open the keys page">
    Go to [App Store Connect → Users and Access → Integrations → In-App Purchase](https://appstoreconnect.apple.com/access/integrations/api/subs).
  </Step>

  <Step title="Generate a key">
    Click **"Generate In-App Purchase Key"** and give it a descriptive name (e.g., `Encore Signing Key`).
  </Step>

  <Step title="Copy the Key ID">
    Copy the **Key ID** shown in the table (e.g., `WHJ3V7RXNW`). You'll need this in the Encore dashboard.
  </Step>

  <Step title="Download the .p8 file">
    Click **Download** to save the `.p8` private key file. You can only download this file once — store it securely.
  </Step>
</Steps>

<Warning>
  The `.p8` key file can only be downloaded once. If you lose it, you'll need to generate a new key.
</Warning>

<Note>
  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.
</Note>

***

## Step 3: Link in the Encore Dashboard

1. Go to your app in the [Encore Dashboard](https://dashboard.encorekit.com)
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:

```
{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

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](./targeting-moments#promotional-offer-handling) for per-manager code examples.

***

## Next Steps

* [Targeting Moments](./targeting-moments) — Choose when to present offers and handle promotional purchases
* [Add Subscription Product](../quickstart/add-subscription-product) — Create the base subscription product