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

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

Command Line

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_types[0]"=card \
  -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 \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel"

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

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

Passing in an existing Customer with a populated phone property to the Checkout Session results in the phone number field being pre-filled.

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.

Collect customer phone numbers with Checkout

Enable phone number collection

After the session

Collecting phone numbers for existing customers

See also