Sandbox Testing

Test your in-app purchase implementation using Apple's StoreKit sandbox environment before going to production.

Testing Options

Method	Environment	Requires App Store Connect
StoreKit Configuration File	Xcode Simulator / Device	No
Sandbox Account	Device only	Yes
TestFlight	Device only	Yes

StoreKit Configuration File (Recommended for Development)

The fastest way to test purchases locally without needing App Store Connect.

1. In Xcode, go to File → New → File
2. Select StoreKit Configuration File
3. Add your products (subscriptions, consumables, etc.)
4. In your scheme, set the StoreKit Configuration under Run → Options → StoreKit Configuration

tip

The StoreKit configuration file lets you test the full purchase flow in the simulator — including renewals, cancellations, refunds, and Ask to Buy.

Sandbox Testing (Device)

For more realistic testing on a physical device:

1. Create a Sandbox Apple ID in App Store Connect → Users and Access → Sandbox Testers
2. On your test device, sign out of the App Store
3. Run your app and make a purchase — you'll be prompted to sign in with the sandbox account

Sandbox Subscription Behavior

Sandbox subscriptions renew at an accelerated rate:

Duration	Sandbox Renewal
1 week	3 minutes
1 month	5 minutes
2 months	10 minutes
3 months	15 minutes
6 months	30 minutes
1 year	1 hour

Subscriptions auto-renew up to 6-12 times in sandbox, then expire.

Debugging Tips

Enable SDK Logging

iOS

// Local mode
AppActor.configure(
  projectKey: "myapp",
  logLevel: .debug,  // Enable verbose SDK logging
  offerings: { /* ... */ },
  entitlements: { /* ... */ }
)

// Payment mode
AppActor.configure(
  apiKey: "pk_test_your_key",
  options: .init(logLevel: .debug)
)

Android

Coming Soon

Android SDK is currently in development.

Flutter

Coming Soon

Flutter SDK is currently in development.

React Native

Coming Soon

React Native SDK is currently in development.

SDK logs appear in Xcode's console with the [AppActor] prefix. Key events logged:

Event	Level
Configuration success/failure	info/error
Product fetch results	info/warning
Transaction processing	info
Purchase outcomes	info
Entitlement rebuilds	debug
Cache operations	debug

Common Issues

Products not loading:

• Verify product IDs match App Store Connect exactly
• Check that your Paid Applications agreement is signed
• Ensure the StoreKit configuration file is selected in your scheme

Purchases failing:

• Check that you're signed in with a sandbox account (not a production Apple ID)
• Verify your app's bundle ID matches App Store Connect

Entitlements not updating:

• Call onAppForeground() to refresh state
• Use getCustomerInfo(forceRefresh: true) for an immediate check
• Check SDK logs for transaction processing details

Sandbox renewals not working:

• Sandbox renewals happen every 3-5 minutes (not at production intervals)
• Each subscription renews 6-12 times, then expires with autoRenew: false
• Make sure Transaction.updates listener is active (call onAppForeground())

TestFlight Testing

TestFlight uses the sandbox environment automatically. Your testers can make purchases without being charged.

1. Upload your build to App Store Connect
2. Add testers (internal or external)
3. Testers install via TestFlight and can test purchases

info

TestFlight builds use the sandbox environment. Purchases are free and subscriptions renew at accelerated rates.

Next Steps

• Launch Checklist — Verify everything before production