T-Mobile eSIM app

T-Mobile eSIM is an app that lets Apple iPhones with dual SIM support activate new T-Mobile prepaid service.


No trekking to a store or juggling two different physical SIM cards – adding a line is done from the app, wherever you are.




About the app

The eSIM app was built for travelers coming to the U.S., existing T-Mobile customers who want a secondary pre-paid line, and anyone who wants to take the Un-carrier out for a test drive to try out America’s fastest 4G LTE network.


  • The app can only activate a T-Mobile prepaid line.
  • For postpaid accounts, check out T-Mobile eSIM.
  • Only available for Apple iPhone XS, iPhone XS Max, or iPhone XR running iOS 12.1.1 or later.
  • The app requires:
    • You have a data connection, through either Wi-Fi or Cellular.
    • You either purchased the iPhone from T-Mobile, or else you must first SIM unlock it. (Contact the original provider if you need help.)
  • There are no fees to activate an iPhone with an eSIM.
  • To activate your iPhone eSIM on another wireless provider or manage eSIM settings, see eSIM settings: Apple iPhone on iOS 13.


T-Moible eSIM app icon.tmp.png


Activate T-Mobile service

Simulators are available to show these steps!


  1. Download and install T-Mobile eSIM app from the Apple App Store.
  2. Open the app, and review the welcome screen.
  3. Tap Get Started.
  4. Enter your email address, and tap Next. (If you already have T-Mobile, you'll need to use a different email address that's not used with a T-Mobile ID.)
  5. If prompted, tap Settings and enable Location Services for the app. Set it to While using the App.
  6. Enter the address for the primary place you'll use T-Mobile service, usually your home, and tap Next.
  7. Make sure your address is correct on the pop-up, and tap Confirm.
  8. Choose your prepaid plan, and tap Next. (Tap See plan details for more information on the plans.)
  9. Review the Service terms, and tap Accept if you agree.
  10. Enter your credit card information (including the CVC/CCC and billing zip code), and tap Next.
  11. Review your order to make sure everything looks correct.
  12. Enter a new PIN, confirm it, and tap Submit.
  13. Wait while we set up your T-Mobile service.
  14. On the "Install Cellular Plan" screen, tap Continue to download and install your eSIM profile.
  15. Tap Add Cellular Plan.
  16. Label your cellular plans for easy identification, and tap Continue.
  17. Choose which line you want to use as your default line, and tap Continue.
  18. Once that's complete, the screen shows your new phone number and lets you view your receipt.
  19. If you want to use a phone number from another provider or from another line, contact us to get this started.


For more instructions on how to set up and use your eSIM line after the activation has completed, please visit https://support.apple.com/en-us/HT209044.



Errors and support

Here are some error messages you may receive using the app and tips to solve them.


Oops, you lost connection
  • This means the app lost its connection to the internet when trying to set up service.
  • Make sure you have good Wi-Fi or Cellular signal, and try again.
  • If possible, try again using a different Wi-Fi network.
Oops, your receipt isn’t ready yet
  • This means that your receipt hasn't finished loading yet. It could take a minute.
  • You can also view the receipt on My T-Mobile under your account history..
Error 501: Device is incompatible or locked by your provider
  • This means your iPhone doesn't have an eSIM or is locked to the service provider you purchased it from.
  • Make sure you have the Apple iPhone XS, iPhone XS Max, or iPhone XR.
  • Contact the service provider who sold you the device to request an unlock.
Error 502: That email is already a T-Mobile account
  • This means the email address you're trying to use is already set up with an existing T-Mobile account.
  • Try again with a different email address to create a new account.
Error 503: eSIM limit reached on this device
Error 504: Oops, something went wrong
  • This means that the app had an issue loading the next screen.
  • Make sure you have a strong Wi-Fi or Cellular data connection, and try again.
  • If it's still not working, contact us for help.
Error 505: There was an issue completing your order
  • This means that something other than the issues above is causing problems.
  • Make sure you have a strong Wi-Fi or Cellular data connection, and try again.
  • If it's still not working, contact us for additional support.
Error 506: It looks like your ZIP code has no remaining phone numbers