Collect customer phone numbers with Checkout
Learn how to collect phone numbers with Checkout.
You can enable phone number collection in Checkout if you need to collect a phone number for shipping or invoicing. Only collect phone numbers if you need them for the transaction. You can enable phone number collection on all payment
and subscription
mode Sessions (phone number collection isn’t supported in setup
mode). This guide assumes that you’ve already integrated Checkout. If you haven’t, see the guide.
Enable phone number collection![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To enable phone number collection, set phone_number_collection[enabled] to true
when creating a Checkout session.
Note
The above code example creates a Session in payment
mode with phone number collection enabled. To enable phone number collection in subscription
mode, make the same changes highlighted in green to your subscription
mode Session creation request.
With phone number collection enabled, Checkout adds a required phone number field to the payment form. If you’re collecting a shipping address, the phone number field displays under the address fields. Otherwise, Checkout displays the phone number field below the email input. Customers can only enter one phone number per session.
After the session![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After the session, you can retrieve customer phone numbers from the resulting Customer, or Checkout Session objects:
- On the Customer: Checkout saves collected phone numbers onto the phone property of the Customer object, which you can access programmatically by either fetching the Customer object directly with the API, or by listening for the customer.created event in a webhook. You can also view the customer’s phone number in the dashboard.
- On the Checkout Session: The customer’s phone number is also saved in the customer_details hash of the Checkout Session object, under customer_details.phone. After each successful Checkout Session, Stripe emits the checkout.session.completed event containing the Checkout Session object (and phone number), which you can listen for in a webhook.
Collecting phone numbers for existing customers![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Passing in an existing Customer with a populated phone property to the Checkout Session results in the phone number field being prefilled.
If the customer updates their phone number, this updated value persists on the phone property on the Customer object , overwriting any previously saved phone number.
Phone number updates using the customer portal ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can allow customers to manage their own accounts (which includes updating their phone numbers) in the customer portal.