Collect customer phone numbers

To enable phone number collection, set phone_number_collection[enabled] to true when creating a Checkout Session.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "line_items[0][price_data][unit_amount]"=1000 \
  -d "line_items[0][price_data][product_data][name]"=T-shirt \
  -d "line_items[0][price_data][currency]"=eur \
  -d "line_items[0][quantity]"=2 \
  -d "phone_number_collection[enabled]"=true \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

This example creates a Session in payment mode with phone number collection enabled. To enable phone number collection in subscription mode, make the same highlighted change 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, 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.

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.

Update phone numbers with the customer portal

You can allow customers to manage their own accounts (which includes updating their phone numbers) in the customer portal.