T-Mobile eSIM app

T-Mobile eSIM is a T-Mobile-branded app that lets Apple iPhones with dual SIM support set up their eSIM and activate T-Mobile prepaid service.




About the app

  • Only available for Apple iPhone XS, iPhone XS Max, or iPhone XR running iOS 12.1.1 or later.
  • If your device isn't from T-Mobile, it must be unlocked to activate with the T-Mobile eSIM app.
  • Requires an active data connection through cellular or Wi-Fi.
  • You can only activate T-Mobile prepaid service using the app.
  • Simulators are available!
  • For information on managing eSIM settings, see eSIM settings: Apple iPhone on iOS 12 .


T-Moible eSIM app icon.tmp.png


Activate T-Mobile service

  1. Download and install T-Mobile eSIM app from the Apple App Store.
  2. Open the app, review the intro screen, then tap Get Started.
  3. 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 in use with a T-Mobile ID.
  4. If prompted, tap Settings and enable Location Services for the app. It needs to be set to "While using the App".
  5. Enter the address for the primary place you'll use T-Mobile service, usually your home, then tap Next.
  6. If your address is correct on the pop-up, tap Confirm.
  7. Choose your prepaid plan, then tap Next. Tap See plan details for more information on the plans.
  8. Review the Service terms, then tap Accept if you agree to the terms.
  9. Enter your credit card information, including the CVC/CCC and billing zip code, then tap Next.
  10. Review your order to make sure everything looks correct. Enter a new PIN, confirm it, then tap Submit.
  11. Wait while we set up your T-Mobile service.
  12. On the Install Cellular Plan screen, tap Continue to download and install your eSIM profile.
  13. Tap Add Cellular Plan, label your cellular plans for easy identification, then tap Continue.
  14. Choose which line you want to use as your default line, then tap Continue.
  15. Once that's complete, the screen will show your new phone number and let you view your receipt.
  16. Contact us if you want to port in your current number from another service provider.


Additional support

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


Oops, you lost connection

  • This means the app lost its connection to the internet when trying to complete setup.
  • Make sure you have good Wi-Fi or Cellular signal and try again.
  • If possible, attempt using a different internet connection.


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.
  • You'll need 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 additional support.


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




What do I need to do to use the eSIM with T-Mobile?

Getting started is easy. You’ll first need an iPhone XS, XS Max, or XR with iOS 12.1.1 or later purchased from T-Mobile or unlocked if purchased from another retailer. Then download the T-Mobile eSIM app from the App Store. Enter an email address to create your new T-Mobile prepaid account and then follow the activation steps to select your plan. Current T-Mobile customers will have to enter a new email address if it’s already connected to a T-Mobile account.


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.


What plans are available for T-Mobile eSIM activation?

T-Mobile offers three prepaid plans for eSIM activation. They are:

  • T-Mobile ONE Prepaid with unlimited voice, text, and data for $70; 30 day expiry with renewal option
  • Simply Prepaid with unlimited voice, text, and 10GB of LTE data for $40; 30 day expiry with renewal option
  • Tourist Plan with 1000 minutes, unlimited text, and 2GB of LTE data for $30; 21 day expiry


Do I need to pay any fees to activate eSIM with T-Mobile?

At this time there are no fees to activate eSIM with T-Mobile.


Can I activate eSIM as a standalone account at T-Mobile?

Yes. If you already have an iPhone from another provider and want to activate a prepaid line, you can activate eSIM as your standalone T-Mobile account. However, if your iPhone is locked to another service provider, you will need to unlock it before you can activate a T-Mobile eSIM.


Why are you choosing to support eSIM with an app?

T-Mobile is making it simple to light up eSIM. Just download the app and select a prepaid plan that works for you. No trekking to a store or juggling two different physical SIM cards – adding a line is done from the convenience of the app, wherever you are. 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.



Click the link below to view the full term & conditions.