Skip to content
AppDues
Log in
Contact salesSign up

iOS Subscription Testing: Sandbox, TestFlight, and Production Checklist

Subscription bugs are expensive: a paywall that unlocks the wrong state, a renewal that never appears, or a restore button that finds nothing can cost real revenue. This guide walks through the three iOS testing environments, the procedures that matter in each, and the edge cases that are easy to miss. Use it as a working checklist before you ship.

The three iOS testing environments

Apple gives you three places to exercise subscription code, and they do not behave the same way. The developer sandbox is for Xcode developer builds and internal QA. TestFlight is the production sandbox: it uses production App Store accounts but cannot charge testers. Production is the live App Store, where real money changes hands.

A practical rule is to test in all three before release. The sandbox is fast and forgiving; TestFlight is closer to real account behavior; production is the only place where refunds, cancellations, and real billing periods behave exactly as customers will see them.

Developer sandbox: fast cycles, real quirks

The developer sandbox is your first line of defence. Build the app as a developer build in Xcode, then provision devices for QA and internal testers. Apple limits device provisioning to 100 per device type (iPhone, iPad, Apple Watch, Apple TV, and Mac), for a total of 500 devices.

To sign in with a new sandbox account for the first time, attempt a purchase in a developer build. After that, you can manage accounts in Settings > iTunes & App Store > Sandbox Account. If a sandbox account is ever used on the production App Store, it will stop working in the sandbox. When a login behaves unexpectedly, the quickest remedy is to make a new sandbox account and run the test again. The Sandbox Account section appeared in iOS 12; on iOS 11 or earlier you sign out of the production account and sign in when prompted inside the app.

Expect repeated sign-in prompts during a purchase. That is a sandbox quirk, not a production behavior. Sign in each time the dialog appears; eventually iOS lets the purchase through.

Reliability: treat sandbox failures as error-handling practice

The developer sandbox is notoriously unreliable. It is unclear whether Apple degrades it on purpose to mimic production issues or simply uses it as its own sandbox and breaks it by accident. Either way, intermittent failures do not always mean your code is wrong. Use those moments to exercise unexpected-error paths. You can also check the sandbox environment's uptime on {{OWNER_SANDBOX_STATUS_URL}}.

That said, never assume a bug will disappear in production. Known sandbox quirks are documented here, but you should still be able to test purchases end to end in the sandbox before shipping.

Subscription renewal rates in the developer sandbox

Sandbox subscriptions and trials are shortened so you can test purchases, renewals, and expirations quickly. The table below shows the captured reference durations. These are a dated reference from the original guide; check Apple's current documentation before relying on them.

Sandbox testing procedures

Renewals and expiration. Sign up for a monthly subscription, close the app, and set a 20-minute timer. Relaunch after 20 minutes to confirm the app is still subscribed. Close again and wait another 20 minutes. At roughly 40 minutes after purchase, the app should revert to the unsubscribed state and allow resubscription.

Restoring after expiration. Subscribe, close the app, and wait 35 to 40 minutes. Relaunch; the app should be unsubscribed. Tap Restore Purchases. No active subscription should be found, and the user should see a message saying so.

Restoring during an active subscription. The sandbox has no receipt file on the device until a purchase is made. To test restore during an active cycle, add a button or gesture that reverts the app to the unsubscribed state. Subscribe, revert, tap Restore Purchases, and confirm the app returns to the subscribed state before the 35-minute cycle ends.

Restoring across devices. Subscribe on device A. Install the app on device B before expiration, sign in to the same sandbox account, launch, and tap Restore Purchases.

Cancellations. Subscribe and confirm the subscribed state. Go to Settings > App Store > your sandbox account > Manage > Subscriptions, cancel, and agree to the terms. Close the app, wait 10 minutes, relaunch, and confirm no active subscription is found.

Upgrades, downgrades, and crossgrades. The sandbox subscription management screen is available as of iOS 14. On older iOS versions, expose in-app buttons to trigger product changes. Subscribe, close the app, open the management screen, choose a different product, and wait 5-10 minutes after a downgrade. Relaunch; the user should be subscribed to the new product.

Interrupted purchases. This behavior requires iOS 14. In App Store Connect > Users and Access > Sandbox Testers, enable "Interrupt Purchases for This Tester." Purchase an auto-renewable subscription, decline the terms and conditions, and confirm the app did not unlock and the receipt does not contain the purchase. Purchase again, accept the terms, refresh, and confirm a valid subscription.

Sandbox takeaways

Three points are worth carrying forward. Subscriptions renew at an accelerated rate in the sandbox. There is no receipt available in the sandbox until a purchase is made. And if you test with StoreKitTest, do not forget to periodically test in the actual sandbox environment.

Trial eligibility in the developer sandbox

If your app offers introductory offers or free trials, test that only eligible users see trial messaging on the paywall. Use a fresh sandbox tester account, run the app, and confirm the correct copy appears. Purchase the product, cancel immediately, and wait for the trial to expire using the shortened sandbox durations above.

After expiration, open the paywall again. The copy should no longer promise a free trial. To repeat the test, reset the sandbox user's trial eligibility using Apple's instructions.

StoreKitTest: local simulation in Xcode

As of iOS 14, the StoreKitTest framework lets you simulate StoreKit locally in Xcode, including products, purchases, and the subscription lifecycle. It is often faster than Apple's sandbox. Use it for things like locking and unlocking content, but always do at least some final testing in the sandbox to confirm your App Store Connect configuration works.

By default, StoreKitTest subscriptions renew in real time. To change the renewal rate, open the StoreKitTest Configuration File in Xcode, go to Editor > Subscription Renewal Rate, and choose a rate.

TestFlight: production sandbox with production accounts

TestFlight behaves like the sandbox but uses production App Store accounts. An app distributed via TestFlight automatically uses the production sandbox for purchases. Testers cannot be charged, but they can view the paywall and step through the purchase flow.

As of December 2024, Apple changed TestFlight subscription renewals to occur once every 24 hours, regardless of subscription duration. Previously, TestFlight subscriptions renewed every few minutes, allowing rapid testing of multiple billing cycles in a single day. This change was not formally announced but appears in Apple's documentation. Testing subscription lifecycles in TestFlight is now significantly slower.

Switching purchase states in TestFlight

Add a button or secret gesture to the TestFlight build that switches the app between purchase states, and set a build flag that removes it from the App Store build. Mention it in the TestFlight release notes when you recruit beta testers.

TestFlight uses the production sandbox, but the build you submit to TestFlight should be the same one that goes to the App Store. If you have staging and production backends, TestFlight runs on your production backend while purchases go to the production sandbox. A typical setup is:

Communicating with TestFlight beta testers

Because TestFlight limits subscription testing, many developers unlock all features for beta testers. Do not rely on TestFlight testers to test price, A/B test paywalls, or measure conversion. Apple does not allow charging TestFlight users, and beta testers are typically loyal users, not a representative sample.

It can still help to have a few testers view the paywall and walk through the purchase flow. Most people skim release notes, so locking everyone out of premium features is a poor trade. A better option is to unlock all features and put paywall testing instructions in the release notes, so readers can help and everyone else can test premium features. A button or secret gesture that reverts the app to the free state lets savvy testers encounter the paywall as real users will.

TestFlight testing procedures should match the sandbox procedures.

Production testing

For an app not yet released, getting an early version approved is a good way to test subscriptions. Submit a beta version to App Review and set Version Release to "Manually release this version" so the app is not released. Generate promo codes for the approved but not-yet-live app, download it with a promo code, and subscribe. Because the app has been approved, subscriptions behave as they will when live, including charging testers and allowing subscription management in the App Store app. Promo-code subscriptions work like paid subscriptions except they do not auto-renew.

Apps downloaded via promo codes before launch may not have a proper receipt file in the download bundle. The receipt should refresh with a purchase, but this can be used to test the rare case where a real user has no accurate receipt in the bundle.

Adding new products in production

The app and its in-app purchases may not propagate to the App Store at the same time. This seems to affect only new products, not previously released ones. It can take more than 24 hours for a new app, update, or product to be available, and the app may appear hours before products can be purchased. Wait 24+ hours after approval and try again.

Production testing procedures

Renewals and expirations are hard to test in production because durations are not shortened. A monthly renewal takes a month; an annual expiration takes a year. That is why Apple shortens durations in the sandbox. If renewals and expirations work there, they should work on the App Store.

Cancellations. Subscribe to a monthly plan and confirm features unlock. Cancel in the App Store app and wait a minute or two for Apple to add the cancellation to the payment queue. Reopen the app. Auto-renew should be disabled on the receipt, the app should remain subscribed, and it should revert to unsubscribed after the current billing period.

Refunds. Subscribe and confirm features unlock. Request a refund from Apple and wait a day for processing. Reopen the app. The refund event should be read from the payment queue and the app should revert to unsubscribed.

Restoring purchases. Subscribe, delete the app, restart the device, and reinstall. Launch and, if necessary, tap Restore Purchases. An active subscription should be found and the app should switch to subscribed.

Free trials and introductory offers. Make sure the app presents introductory offers only to eligible users. Once an account redeems an introductory offer, it is no longer eligible for introductory offers for any product in the same subscription group. There does not appear to be a way to reset this other than creating a fresh sandbox account. Getting eligibility wrong is a frequent cause of rejection, so err on the side of making everyone eligible rather than everyone ineligible.

Subscription offers. iOS Subscription Offers can only be redeemed in sandbox after a subscription has expired, related to product changes not working in sandbox. In production, active or lapsed subscribers can redeem an offer.

QA checklist

Developer sandbox: test purchasing a subscription; test renewals and expiration; test restoring after expiration; test restoring during an active subscription; test restoring across devices.

TestFlight: test purchasing a subscription; test renewals and expiration; test restoring after expiration; test restoring during an active subscription; test restoring across devices.

Production: test a purchase before launch day; test a purchase on launch day; test cancelling a subscription; test refunding a purchase; test restoring a purchase.

Bonus iOS testing tips

Promo codes. You can generate subscription promo codes in App Store Connect, but note the caveats. A promo-code subscription does not auto-renew; after the free period, the user must purchase normally. Giving a promo code to an existing subscriber cancels their existing subscription and replaces it with a non-renewing free period. Paid apps need a separate promo code for the download. The receipt contains no indication that a promo code was used, so tracking is difficult.

Offer codes. Offer codes work like promo codes without many of the caveats. They can be redeemed in your app's payment screen or in the App Store via a deep link. Offer codes cannot be fully tested in sandbox; if purchasing works in sandbox, you can trust offer codes in production.

TestFlight invites. You do not need a user's App Store account email to invite them to TestFlight. Send the invite to any email address. When the user taps the unique link, the invite associates with whatever App Store account is logged in on that device. Future beta emails go to the original address, and Apple does not add the App Store account email to your tester list.

Missing receipts. An App Store download should always include a receipt in the app bundle, but sometimes it does not. One theory is that restoring a device from an iTunes backup does not transfer the receipt, likely to prevent tampering. iOS does not automatically download a fresh receipt in these cases. Handle the no-receipt edge case and provide an easy-to-find Restore Purchases button. Do not automatically refresh the receipt, because that triggers a system-level password request that many users cancel.

Adding new products. Once live, you can add products and get them approved without an app update. After approval, products can take up to 24 hours to propagate. Set up your paywall so new offerings can be enabled remotely. A typical sequence: the app is live with monthly_product_1; you create and submit monthly_product_2; Apple approves it; wait 24 hours; switch the app to display monthly_product_2 through a remote configuration setting.

Subscription disclosures. Apple used to require extensive terms on the paywall, but those requirements have been relaxed. You no longer need to link to Terms of Service and Privacy Policy on the paywall, though they must be linked somewhere in the app. The three required items on the paywall are the subscription name, the subscription length, and the subscription price (and price per unit, if appropriate).

Final thoughts. If you have questions this guide does not answer, reach out via {{OWNER_CONTACT_URL}} or {{OWNER_TWITTER_HANDLE}}. If you are implementing or scaling in-app subscriptions, the open-source SDKs at {{OWNER_SDK_DOCS_URL}} handle the common pain points so you can focus on building your app.

Which environment should you use for which check?

Use the developer sandbox for fast iteration on purchase, renewal, expiration, restore, cancellation, upgrade, downgrade, crossgrade, and interrupted-purchase flows. Use StoreKitTest for local, repeatable content-locking checks and rapid lifecycle simulation. Use TestFlight for a final pass with production accounts and your production backend, keeping in mind the 24-hour renewal interval. Use production for pre-launch promo-code purchases, launch-day purchases, cancellations, refunds, and restores, and for confirming that new products propagate.

A useful failure distinction: if a flow fails only in the developer sandbox and passes in TestFlight and production, treat it as a sandbox quirk and verify error handling. If it fails in TestFlight or production, treat it as a real defect. If it fails only after a new product is added, check propagation timing before changing code.

Worked example: a one-month sandbox cycle

Suppose your product is a one-month auto-renewable subscription. In the developer sandbox, the captured reference duration is 5 minutes per cycle, and subscriptions renew up to 12 times per account, with the actual number of renewals random. After at most 12 renewals, the subscription stops renewing.

A practical test plan: purchase at T+0, close the app, and reopen after 5 minutes to confirm the first renewal appears in the receipt. Repeat at 10 and 15 minutes. After the final renewal, wait for the cycle to end and reopen the app to confirm it reverts to unsubscribed. Because renewals are added to the payment queue and processed when the app opens, closing and reopening is part of the test, not an inconvenience. If you refresh receipts server-side, confirm the additional transactions appear there too.

This example uses the captured reference durations. Check Apple's current sandbox behavior before relying on exact timings.

Paywall disclosure field map

The paywall needs three reader-facing fields: the subscription name, the subscription length, and the subscription price, including price per unit where appropriate. Terms of Service and Privacy Policy links must exist somewhere in the app, but they are not required on the paywall itself. Pair these fields with a visible Restore Purchases control, and make sure the control is reachable when no receipt is present.

Captured reference: App Store vs. sandbox vs. TestFlight subscription durations
App Store DurationSandbox DurationTestflight
3 days2 minutes1 day
1 week3 minutes1 day
1 month5 minutes1 day
2 months10 minutes1 day
3 months15 minutes1 day
6 months30 minutes1 day
1 year1 hour1 day

Dated reference from the original guide. Check Apple's current documentation before relying on exact durations.

Captured reference: typical environment pairing
App VersionApp StoreYour Backend
SandboxSandboxStaging
TestFlightProduction SandboxProduction
App StoreProductionProduction

Typical setup as described in the original guide; your architecture may differ.

Frequently asked questions

Why does the developer sandbox fail intermittently?

The developer sandbox is known to be unreliable. It is unclear whether Apple degrades it intentionally or breaks it by accident. Treat intermittent failures as opportunities to test error handling, but do not assume a bug will disappear in production.

How often do TestFlight subscriptions renew?

As of December 2024, TestFlight subscriptions renew once every 24 hours, regardless of subscription duration. Previously they renewed every few minutes. This makes lifecycle testing in TestFlight much slower.

What should the app do when no receipt is present?

Handle the no-receipt edge case and show an easy-to-find Restore Purchases button. Do not automatically refresh the receipt, because that triggers a system-level password request that many users cancel.

Can offer codes be fully tested in sandbox?

No. Offer codes cannot be fully tested in the sandbox. If purchasing works in sandbox, you can trust offer codes in production.

How do I reset introductory offer eligibility?

Once an account redeems an introductory offer, it is no longer eligible for introductory offers for any product in the same subscription group. There does not appear to be a way to reset this other than creating a fresh sandbox account. Apple provides instructions for resetting a sandbox user's trial eligibility.