Guide · App Store Connect

App Store offer codes: create, share and track them

App Store offer codes are codes you create in App Store Connect that give someone a subscription or in-app purchase free or at a discount. There are two kinds: one-time use codes that Apple generates in batches, and custom codes you name yourself (like SPRINGPROMO) that many people can redeem.

Since October 29, 2025, offer codes work for every in-app purchase type: consumables, non-consumables and non-renewing subscriptions as well as auto-renewable subscriptions. Each app can create up to 1 million codes per quarter, shared across all its products.

Customers redeem a code through a redemption link, in the App Store (one-time use codes only) or inside your app through StoreKit's redemption sheet. Apple runs the offer screen and the payment; your app only has to grant what the resulting transaction says.

By Redjan Hysa, founder of MetaRun · Facts checked October 12, 2026

codes per app per quarter, shared across products: 1,000,000
active offers at a time (per subscription, for subscriptions): 10
one-time use codes per batch: 500 to 25,000
longest validity of a one-time use code: 6 months
characters max in a custom code: 64
before new codes can be redeemed: Up to 1 hour

01 · Reference

Reference tables

One-time use codes vs custom codes

	One-time use codes	Custom codes
What they look like	Unique codes Apple generates (Apple calls them 18-digit codes)	Your own code, up to 64 characters, no special characters
Redemptions per code	One	Up to the limit you set, max 25,000 per batch
Batch size	500 to 25,000 codes	One code with a redemption limit
Expiry	Required, up to 6 months	Optional: up to 6 months, or No End Date
Where customers redeem	Redemption link, App Store, or in-app sheet	Redemption link or in-app sheet
Suited to	Targeted handouts: support cases, events, partners	Mass campaigns: newsletters, podcasts, social posts

Both count toward the 1 million codes per app per quarter. Codes expire at 12:00 a.m. Pacific on the expiry date. Sandbox codes are a third type for testing: 10 to 10,000 per batch, up to 10,000 per app per quarter.

Who can redeem: eligibility options by product type

Product type	Eligibility choices	Extra rules
Auto-renewable subscription	New subscribers (never subscribed in the group), existing subscribers (including billing retry or grace period with auto-renew on), expired subscribers	Choose whether redeemers also get your introductory offer; existing subscribers can only redeem codes at their level or higher
Consumable, non-consumable, non-renewing subscription	Never purchased in your app, purchased in the last 30 days, purchased more than 30 days ago	Tick all three to make the offer available to everyone

02 · By hand

How to create offer codes in App Store Connect

You need the Account Holder, Admin, App Manager or Marketing role. Customers can only redeem once the app is live on the App Store.

01
Start the offer
For a subscription: Subscriptions, the group, the subscription, then the add button (+) in Subscription Prices and Create Offer Codes. For other in-app purchases: open the product under In-App Purchases and click Create Offer in the Offer Codes section.
02
Name it and set eligibility
Enter a reference name; it identifies the offer in Sales and Trends and in StoreKit transactions, and can't be changed later. Pick eligibility. For subscriptions, also decide whether redeemers get your introductory offer and whether the subscription renews after the offer.
03
Pick storefronts, type and price
Select countries or regions, then Pay as you go, Pay up front or Free for a subscription, or Paid Offer or Free Offer for other products. Choose the base price; App Store Connect fills in comparable prices for every storefront. Check it all before Confirm, because offers can't be edited afterwards.
04
Generate codes
Open the offer. Click Create One-Time Use Codes (500 to 25,000 and an expiry date), or Create Custom Codes (the code, a redemption limit up to 25,000 and an optional expiry).
05
Download and share
Download one-time use codes as a CSV, which includes a redemption link per code. Wait up to an hour before sending codes out.
06
Deactivate when the campaign ends
Deactivate a batch to expire its unredeemed codes at once. Deactivating the whole offer is permanent and invalidates all of its codes; people who already redeemed keep what they got.

03 · Briefing

When offer codes are the right offer

Offer codes are the one App Store offer you distribute yourself. Introductory offers go automatically to customers who haven't had one in the group, promotional offers are presented by your app to subscribers you pick, and win-back offers are shown by Apple to lapsed subscribers. A code reaches whoever you hand it to, within the eligibility you set, which suits newsletters, partners, customer support and events. Apple handles the redemption screen, showing your app icon (or the subscription's promotional image), the display name, duration and price.

Codes also replace promo codes for in-app purchases: since March 26, 2026 App Store Connect no longer creates promo codes for in-app purchases. Existing ones work until they expire, and promo codes for free app downloads still exist. Offer codes don't support tvOS-only apps yet.

04 · Briefing

Offer code redemption URL and in-app redemption

Redemption link: one-time use codes come with their links in the CSV, and the offer page shows an example link you add a code to. Developers report the format as https://apps.apple.com/redeem?ctx=offercodes&id=APP_ID&code=CODE, where APP_ID is your app's numeric Apple ID, but copy Apple's example rather than building it by hand. Someone without the app is prompted to download it during redemption.

App Store: one-time use codes can be typed into the App Store's redeem flow (Redeem Gift Card or Code in account settings). Custom codes can't; they need the link or your app.

In your app: call offerCodeRedemption in SwiftUI, or presentOfferCodeRedeemSheet in UIKit and AppKit. The sheet reports invalid entries itself, such as an expired code or one that would downgrade a subscription. Subscription codes work from iOS 14.2 (use the older presentCodeRedemptionSheet on iOS 14 and 15); codes for other in-app purchases need iOS 16.3, macOS 15 or visionOS 1.0 or later. Codes redeemed outside the app arrive as transactions, often while your app isn't running, so listen to Transaction.updates from launch and finish each transaction.

05 · Briefing

Creating offer codes with the App Store Connect API

For subscriptions, POST /v1/subscriptionOfferCodes creates the offer (name, customerEligibilities, offerEligibility, offerMode, duration, numberOfPeriods, plus the subscription and prices relationships). Then POST /v1/subscriptionOfferCodeOneTimeUseCodes (numberOfCodes, expirationDate) or POST /v1/subscriptionOfferCodeCustomCodes (customCode, numberOfCodes, optional expirationDate). GET /v1/subscriptionOfferCodeOneTimeUseCodes/{id}/values returns the codes as CSV. In-app purchases have the same set under inAppPurchaseOfferCodes, and deactivation is a PATCH on the batch or the offer.

Two rules trip up scripts. A free subscription offer's price rows carry no price point at all; Apple rejects one that has a price. And generated codes can't be taken back, so treat minting as irreversible and deactivate instead. MetaRun previews each of these calls, including the per-storefront prices, before anything reaches Apple.

06 · Briefing

Measuring redemptions

Sales and Trends has a Subscription Offer Redemption report: date, subscription, offer reference name, the custom code (blank for one-time use codes), territory and number of redemptions. Analytics in App Store Connect also has an Offers dashboard covering offer codes alongside introductory, promotional and win-back offers.

Per customer, read the transaction. In StoreKit, Transaction.offer has type code. On your server, the signed transaction carries offerType 3 and the offerIdentifier, and App Store Server Notifications send OFFER_REDEEMED for an active subscriber, SUBSCRIBED for a new purchase or resubscribe, and ONE_TIME_CHARGE for other in-app purchases. Since the report doesn't name one-time use codes, give each campaign its own offer and reference name.

07 · Briefing

Offer code limits and rules that catch people

Each customer can redeem one code per offer. An offer can't be edited after creation; to change eligibility, create a new one. Deactivated, unredeemed codes don't go back into the quarterly 1 million. A custom code already used by another offer in the same app has to be deactivated there first. To extend a custom code, create a new batch of the same code with a later expiry; the earliest unexpired batch is redeemed first.

For a subscription offer, ticking the box that stops auto-renewal limits you to free offers, and the customer gets a trial with no commitment. For other in-app purchases, generating one-time use or custom codes requires the app to be Ready for Distribution and the product to be Approved.

08 · Troubleshooting

Common problems and how to fix them

Offer code says not valid, or not available in your country

Why: The code expired (at 12:00 a.m. Pacific on its expiry date), its batch or offer was deactivated, it was created less than an hour ago, the customer doesn't meet the eligibility, or their Apple Account is on a storefront the offer doesn't include. A subscription code that would downgrade the customer is refused too.

Fix: Check the batch's expiry and status on the offer page, confirm the customer's account country or region is in the offer's storefronts, and compare their purchase history with the eligibility you set.

Code already redeemed

Why: One-time use codes work once, each customer gets one code per offer, and a custom code stops at its redemption limit.

Fix: Give that customer a code from a different offer whose eligibility fits them. For a popular custom code, create another batch of the same code to raise the limit.

Can't create more offer codes (limit reached)

Why: The app has used its 1 million codes for the quarter, shared across every product, or the subscription already has 10 active offers. For other in-app purchases, the app must be Ready for Distribution and the product Approved before codes can be generated.

Fix: Deactivate offers you no longer run (permanent), size batches to what you'll hand out, or wait for the next quarter. Unredeemed codes from a deactivated batch don't come back to the quota.

Redeemed code doesn't appear in the app

Why: The redemption happened outside the app and the app isn't listening for transactions, or it never calls finish(). There's also no in-app redeem button unless your app presents StoreKit's sheet.

Fix: Start a Transaction.updates listener at launch, check currentEntitlements and unfinished transactions, grant access and call finish(). Add a Redeem Code button that calls offerCodeRedemption or presentOfferCodeRedeemSheet.

09 · With an AI agent

Do it from Claude Code, Codex, Cursor or Xcode with MetaRun

Apple has four offer types for subscriptions and they target different people: introductory offers for those who never subscribed, promotional offers for current subscribers, offer codes for anyone with a code, and win-back offers for people who left. Each has its own screens in App Store Connect and its own rules about price and eligibility.

MetaRun exposes each one as a preview and apply pair. Your agent can create them, generate one-time codes, turn codes on and off, and read back what's live.

Before you start

A subscription to attach the offer to.
Who the offer is for: new, current, lapsed, or anyone with a code.
Prices per storefront for paid offers; free trials only need territories.

How the agent runs it

01
Match the offer to the audience
Your agent picks the offer type from who it's for: never subscribed, subscribed now, lapsed, or anyone holding a code.
02
Price it per storefront
Paid offers take a price per territory. Free trials take a list of territories instead, because Apple wants no price on a free row.
03
Preview the offer
The preview shows the offer, its duration and where it applies, with a confirm token.
04
Generate and track codes
One-time codes are generated in a batch after the campaign exists. Campaigns can be switched off later without deleting them.

An example session

Add a 7-day free trial to com.example.app.pro.yearly for new subscribers in every storefront.

apple_list_subscription_offersThe yearly plan has no introductory offer.
apple_preview_create_intro_offerPreview: one-week free trial for new subscribers, every territory.
Your agent asks before running apple_apply_create_intro_offer. You read the preview above and approve.
apple_apply_create_intro_offerCreated in every storefront.
apple_preview_create_offer_codePreview: NEWSLETTER, 50% off for three months.

Illustrative: your apps, versions and numbers will differ. The tool names and their order are real.

The MetaRun tools involved

Tool	What it does
apple_list_subscription_offersread	Every offer on a subscription, across all four types.
apple_preview_create_intro_offerpreview + apply	Free trial, pay as you go, or pay up front for new subscribers.
apple_preview_create_promotional_offerpreview + apply	A discount current or lapsed subscribers can redeem in the app.
apple_preview_create_offer_codepreview + apply	An offer code campaign, with custom codes or one-time codes.
apple_preview_generate_offer_codespreview + apply	Mint a batch of one-time-use codes.
apple_preview_set_offer_code_activepreview + apply	Turn a code campaign on or off.
apple_preview_create_winback_offerpreview + apply	A win-back offer for people who cancelled (iOS 18 and later).
apple_preview_create_iap_offer_codepreview + apply	Offer codes for in-app purchases.

Each preview has an apply twin that only runs with the confirm token from a fresh preview, and refuses if App Store Connect changed in between.

What Apple enforces along the way

Intro offers are stored per territory

Apple keeps an introductory offer as one resource per storefront, so a 3-day trial in 175 storefronts is 175 records. MetaRun reads them back as one offer with a territory count.

Free trials carry no price

A free trial's price rows must have no price point. MetaRun takes territories instead of prices for free offers and refuses a mixed request at preview rather than repricing silently.

Issued codes can't be taken back

Generating codes isn't revertible, since a code already handed out can't be un-issued. Deactivating the campaign is the lever instead.

Win-back offers need iOS 18

Win-back offers reach people who subscribed before and cancelled, and only on iOS 18 and later.

Set up your agent

Connect once, then ask in plain words. Pick your agent:

Claude Code Anthropic

Run claude mcp add --transport http --scope user metarun https://metarun.dev/api/mcp, then run /mcp in Claude Code and sign in to MetaRun in your browser.

01 · Add the server

Run it in any terminal. --scope user makes MetaRun available in every project; leave it out to limit it to the current one.

claude mcp add --transport http --scope user metarun https://metarun.dev/api/mcp

02 · Sign in

In a Claude Code session, run /mcp, choose metarun and authenticate. MetaRun opens in your browser, where you pick read-only or read and change. From a plain shell, claude mcp login metarun does the same.

/mcp

03 · Optional: add the skills too

The MetaRun plug-in bundles the same server with six mission skills (release handoff, worldwide pricing, localization, review inbox, ASO audit, store media).

claude plugin marketplace add metarun/metarun-skills
claude plugin install metarun-skills@metarun

Then ask Claude Code

Ask Claude Code: Add a 7-day free trial to com.example.app.pro.yearly for new subscribers in every storefront.
Ask Claude Code: Create an offer code campaign NEWSLETTER for 50% off the first 3 months, and generate 500 one-time codes.
Ask Claude Code: Set up a win-back offer: 2 months at half price for people who cancelled in the last 6 months.

claude -p runs one request with no interactive session. The browser sign-in can't complete inside -p, so sign in once interactively first, or configure the server with a personal access token in CI. Tools missing from --allowedTools are refused in -p mode.

Read-only check, safe to schedule

claude -p "List every offer on each subscription of com.example.app: type, duration, territories and whether it is active. Read only." \
  --allowedTools "mcp__metarun__apple_list_subscription_offers,mcp__metarun__apple_preview_create_intro_offer,mcp__metarun__apple_preview_create_promotional_offer,mcp__metarun__apple_preview_create_offer_code,mcp__metarun__apple_preview_generate_offer_codes,mcp__metarun__apple_preview_set_offer_code_active,mcp__metarun__apple_preview_create_winback_offer,mcp__metarun__apple_preview_create_iap_offer_code"

Only reads and previews are on that list, so nothing can reach App Store Connect unattended. Run applies in an interactive session where Claude Code can ask you.

Full Claude Code setup guide

Codex OpenAI

Run codex mcp add metarun --url https://metarun.dev/api/mcp; Codex detects MetaRun's sign-in and opens it in your browser.

01 · Add the server

Codex sees that MetaRun offers sign-in and starts it straight away, in your browser. Pick read-only or read and change.

codex mcp add metarun --url https://metarun.dev/api/mcp

02 · Sign in again later

If the sign-in expires or you disconnected it in MetaRun's settings. --no-browser prints the link instead, for SSH sessions.

codex mcp login metarun

03 · Or edit ~/.codex/config.toml

The Codex CLI, the IDE extension and Codex in the ChatGPT desktop app read the same file, so one entry covers all three.

[mcp_servers.metarun]
url = "https://metarun.dev/api/mcp"

Then ask Codex

Ask Codex: Add a 7-day free trial to com.example.app.pro.yearly for new subscribers in every storefront.
Ask Codex: Create an offer code campaign NEWSLETTER for 50% off the first 3 months, and generate 500 one-time codes.
Ask Codex: Set up a win-back offer: 2 months at half price for people who cancelled in the last 6 months.

codex exec runs one request without an interactive session and with its approval policy set to never. MetaRun's reads and previews still run, because they're marked read-only; anything that would ask is refused.

Read-only check, safe to schedule

codex exec "List every offer on each subscription of com.example.app: type, duration, territories and whether it is active. Read only."

Applies are refused in codex exec by design. Don't set MetaRun's approval mode to approve just to make them pass; keep App Store changes in an interactive session.

Full Codex setup guide

Cursor Anysphere

Add https://metarun.dev/api/mcp to ~/.cursor/mcp.json (or use the install link) and sign in to MetaRun when Cursor opens your browser.

01 · Add to ~/.cursor/mcp.json (or .cursor/mcp.json for one project)

{
  "mcpServers": {
    "metarun": {
      "url": "https://metarun.dev/api/mcp"
    }
  }
}

02 · Or use the install link

Opens Cursor with the server filled in.

https://cursor.com/link/mcp/install?name=metarun&config=eyJ1cmwiOiJodHRwczovL21ldGFydW4uZGV2L2FwaS9tY3AifQ%3D%3D

03 · Sign in

When Cursor connects, MetaRun opens in your browser. Pick read-only or read and change, and you're back in the editor with the tools listed under MCP.

Then ask Cursor

Ask Cursor: List every offer on the yearly plan and which ones are active.
Ask Cursor: Turn off the SUMMER offer codes.
Ask Cursor: Add a pay-up-front intro offer: first year at $19.99 in the US, PPP elsewhere.

The Cursor CLI runs one request without the editor with agent -p. Allow only the read tools the request needs in ~/.cursor/cli-config.json (Mcp(metarun:tool_name) rules), and keep MetaRun's apply tools out of that list.

Read-only check, safe to schedule

agent -p "List every offer on each subscription of com.example.app: type, duration, territories and whether it is active. Read only." --output-format json

Don't run it with --force for MetaRun: that approves every tool, applies included.

Full Cursor setup guide

Xcode Apple

In Xcode 27, add the plug-in from https://github.com/metarun/metarun-skills (Settings, Intelligence, Plug-ins, Add from URL) and click Sign in next to MetaRun.

01 · Add the MetaRun plug-in

In Xcode 27, open Settings, Intelligence, Plug-ins. Choose Add Plug-in, then Add from URL, and paste:

https://github.com/metarun/metarun-skills

02 · Or with one click

Opens Xcode's plug-in sheet with the repository filled in.

xcode://agent-plugin-clone?repo=https%3A%2F%2Fgithub.com%2Fmetarun%2Fmetarun-skills

03 · Sign in

Install MetaRun from the list, then click Sign in next to it. MetaRun opens in your browser; pick read-only or read and change.

04 · Ask the coding assistant

Claude Agent, Codex and Gemini in Xcode all get MetaRun's tools and its six workflow skills.

Attach build 312 to version 2.4 and tell me what blocks submission.

Then ask Xcode

Ask Xcode: Our paywall shows a free trial. Make sure the yearly plan actually has one in every storefront we sell in.
Ask Xcode: Create a promotional offer we can present from the app for users who downgrade.
Ask Xcode: Generate 200 one-time codes for the beta testers.

Full Xcode setup guide

Claude Anthropic

In Claude, open Customize, Connectors, Add custom connector, paste https://metarun.dev/api/mcp and click Connect to sign in to MetaRun.

01 · Add a custom connector

In Claude, open Customize, then Connectors, and choose Add custom connector. Name it MetaRun and paste the server URL:

https://metarun.dev/api/mcp

02 · Connect

Click Connect. Claude opens MetaRun in your browser to sign in; pick read-only or read and change.

03 · Team and Enterprise

An Owner adds the connector once under Organization settings, Connectors. Each member then clicks Connect and signs in to their own MetaRun account.

Then ask Claude

Ask Claude: Give new subscribers a one-week free trial.
Ask Claude: Make a discount code for my podcast listeners.
Ask Claude: Which offers are running on my subscriptions?

Full Claude setup guide

Apple key stays on MetaRun, encryptedPreview before every writeRecorded, revertible from history

10 · FAQ

Frequently asked questions

Can I use offer codes for in-app purchases?

Yes. Since October 29, 2025 offer codes cover consumables, non-consumables and non-renewing subscriptions as well as auto-renewable subscriptions. Redeeming those codes needs iOS 16.3, macOS 15 or visionOS 1.0 or later.

What's the App Store offer codes limit?

Up to 1 million codes per app per quarter, shared across all products, and 10 active offers at a time (per subscription for subscriptions). One-time use batches run 500 to 25,000 codes; a custom code takes up to 25,000 redemptions per batch.

One-time use codes vs custom codes: which should I use?

One-time use codes when each code goes to a specific person and you need to control who redeems, like support cases or contest winners. Custom codes when one memorable code goes out widely, like a podcast or newsletter promo. Custom codes can't be typed into the App Store, so share them as a link or redeem them in your app.

How do I get an offer code redemption URL?

For one-time use codes, download the batch: the CSV includes a link for each code. Otherwise copy the example link from the offer's page in App Store Connect and add the code to the end.

Can offer codes give a free trial?

Yes. Subscription offer codes support Free alongside Pay as you go and Pay up front, and you can stop the subscription renewing after the offer. Other in-app purchases offer Paid or Free.

Can I edit an offer code after creating it?

No. Offers and custom codes can't be edited, and expiry dates are fixed. Create a new offer, or a new batch of the same custom code, and deactivate the old one.

Which offer type should I use?

Introductory offers for people who never subscribed, promotional offers for current subscribers, win-back offers for people who left, and offer codes when you hand out a code yourself. Your agent can pick based on who you describe.

Can your agent generate one-time offer codes?

Yes. Create the campaign, then generate a batch of one-time-use codes. Generation isn't revertible, so it always previews first.

Can I offer a free trial in some countries only?

Yes. Free trials take a list of territories; leave it out for every storefront.

Do offers work for in-app purchases?

Offer codes do, through apple_preview_create_iap_offer_code. Introductory, promotional and win-back offers are subscription features in Apple's model.

11 · Sources

Sources

Related guides

Guide

Create a subscription

Groups, levels, prices and the Missing Metadata checklist, through to the first submission and later price changes.

Guide

Pricing by country

How Apple equalizes one base price into 175 storefronts, how to override them, and PPP vs flat pricing.

Guide

Price tiers by country

Apple's current price for $0.99 to $99.99 in all 175 storefronts, and what you keep at 15% and 30%.

All guides

Every App Store Connect guide

Releases, TestFlight, pricing, subscriptions, localization, screenshots and more.

With MetaRun: Offers and prices in every storefront

MetaRun

Do this from your AI agent or MetaRun's dashboard, with a preview before every change. 14-day free trial, no card.

Start Free Trial See pricing →

Reference tables

How to create offer codes in App Store Connect

Start the offer

Name it and set eligibility

Pick storefronts, type and price

Generate codes

Download and share

Deactivate when the campaign ends

When offer codes are the right offer

Offer code redemption URL and in-app redemption

Creating offer codes with the App Store Connect API

Measuring redemptions

Offer code limits and rules that catch people

Common problems and how to fix them

Offer code says not valid, or not available in your country

Code already redeemed

Can't create more offer codes (limit reached)

Redeemed code doesn't appear in the app

Do it from Claude Code, Codex, Cursor or Xcode with MetaRun

Before you start

How the agent runs it

Match the offer to the audience

Price it per storefront

Preview the offer

Generate and track codes

An example session

The MetaRun tools involved

What Apple enforces along the way

Intro offers are stored per territory

Free trials carry no price

Issued codes can't be taken back

Win-back offers need iOS 18

Set up your agent

Frequently asked questions

Can I use offer codes for in-app purchases?

What's the App Store offer codes limit?

One-time use codes vs custom codes: which should I use?

How do I get an offer code redemption URL?

Can offer codes give a free trial?

Can I edit an offer code after creating it?

Which offer type should I use?

Can your agent generate one-time offer codes?

Can I offer a free trial in some countries only?

Do offers work for in-app purchases?

Sources