Extend checkout with custom components

Add custom fields

You can add custom fields on the payment form to collect additional information from your customers. The information is available after the payment is complete and is useful for fulfilling the purchase.

Custom fields have the following limitations:

• Up to three fields allowed.
• Not available in setup mode.
• Support for up to 255 characters on text fields.
• Support for up to 255 digits on numeric fields.
• Support for up to 200 options on dropdown fields.

Create a Checkout Session

Create a Checkout Session while specifying an array of custom fields. Each field must have a unique key that your integration uses to reconcile the field. Also provide a label for the field that you display to your customer. Labels for custom fields aren’t translated, but you can use the locale parameter to set the language of your Checkout Session to match the same language as your labels.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text"

Retrieve custom fields

When your customer completes the Checkout Session, we send a checkout.session.completed webhook with the completed fields.

Example checkout.session.completed payload:

{
  "id": "evt_1Ep24XHssDVaQm2PpwS19Yt0",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1664928000,
  "data": {
    "object": {
      "id": "cs_test_MlZAaTXUMHjWZ7DcXjusJnDU4MxPalbtL5eYrmS2GKxqscDtpJq8QM0k",
      "object": "checkout.session",
      "custom_fields": [{
        "key": "engraving",
        "label": {
          "type": "custom",
          "custom": "Personalized engraving"
        },
        "optional": false,
        "type": "text",
        "text": {
          "value": "Jane"
        }
      }],
      "mode": "payment"
    }
  },
  "livemode": false,

You can also look up and edit custom field values from the Dashboard, by clicking into a specific payment in the Transactions tab or including custom field values when exporting your payments from the Dashboard.

Use a custom field

Mark a field as optional

By default, customers must complete all fields before completing payment. To mark a field as optional, pass in optional=true.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][optional]=true"

Add a dropdown field

A dropdown field presents your customers with a list of options to select from. To create a dropdown field, specify type=dropdown and a list of options, each with a label and a value. The label displays to the customer while your integration uses the value to reconcile which option the customer selected.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=sample" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Free sample" \
  -d "custom_fields[0][optional]=true" \
  -d "custom_fields[0][type]=dropdown" \
  -d "custom_fields[0][dropdown][options][0][label]=Balm sample" \
  -d "custom_fields[0][dropdown][options][0][value]=balm" \
  -d "custom_fields[0][dropdown][options][1][label]=BB cream sample" \
  -d "custom_fields[0][dropdown][options][1][value]=cream"

Add a numbers only field

A numbers-only field provides your customers a text field that only accepts numerical values, up to 255 digits. To create a numbers-only field, specify type=numeric.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=invoice" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Invoice number" \
  -d "custom_fields[0][type]=numeric"

Retrieve custom fields for a subscription

You can retrieve the custom fields associated with a subscription by querying for the Checkout Session that created it using the subscription parameter.

curl -G https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d "subscription=
{{SUBSCRIPTION_ID}}"

Add character length validations

You can optionally specify a minimum and maximum character length requirement for text and numeric field types.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][minimum_length]=10" \
  -d "custom_fields[0][text][maximum_length]=20" \
  -d "custom_fields[0][optional]=true"

Add default values

You can optionally provide a default value for the text, numeric, and dropdown field types. Default values are prefilled on the payment page.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "custom_fields[0][key]=engraving" \
  -d "custom_fields[0][label][type]=custom" \
  -d "custom_fields[0][label][custom]=Personalized engraving" \
  -d "custom_fields[0][type]=text" \
  -d "custom_fields[0][text][default_value]=Stella" \
  -d "custom_fields[1][key]=size" \
  -d "custom_fields[1][label][type]=custom" \
  -d "custom_fields[1][label][custom]=Size" \
  -d "custom_fields[1][type]=dropdown" \
  -d "custom_fields[1][dropdown][default_value]=small" \
  -d "custom_fields[1][dropdown][options][0][value]=small" \
  -d "custom_fields[1][dropdown][options][0][label]=Small" \
  -d "custom_fields[1][dropdown][options][1][value]=large" \
  -d "custom_fields[1][dropdown][options][1][label]=Large"

Customize text and policies

When customers pay with Stripe Checkout, you can present additional text, such as shipping and processing times.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d "shipping_address_collection[allowed_countries][0]=US" \
  --data-urlencode "custom_text[shipping_address][message]=Please note that we can't guarantee 2-day delivery for PO boxes at this time." \
  --data-urlencode "custom_text[submit][message]=We'll email you instructions on how to get started." \
  --data-urlencode "custom_text[after_submit][message]=Learn more about **your purchase** on our [product page](https://www.stripe.com/)." \
  --data-urlencode "success_url=https://example.com/success"

Custom text near the shipping address collection fields

Custom text above the Pay button

Custom text after the Pay button

Your custom text can be up to 1200 characters in length. However, Stripe Checkout is optimized for conversion, and adding extra information might affect your conversion rate. You can bold text or insert a link using Markdown syntax.

Customize the Submit button

To better align Checkout with your business model, configure the text displayed on the Checkout submit button for one-time purchases.

Define a submit_type on your session. In this example (for a 5 USD donation), your customized Checkout submit button displays Donate \5.00 USD. See the API reference for a complete list of submit_type options.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d submit_type=donate \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success"

Localization and supported languages

By default, Checkout detects the locale of the customer’s browser and displays a translated version of the page in their language, if Stripe supports it. You can override the browser locale for Checkout by passing the locale parameter when you create a Checkout Session.

Checkout also uses the locale to format numbers and currencies. For example, when selling a product whose price is set in EUR with the locale set to auto, a browser configured to use English (en) would display €25.00 while one configured for German (de) would display 25,00 €.

Customize policies and contact information

You can display your return, refund, and legal policies, and your support contact information to your customers on Checkout. Go to Checkout Settings to configure the information you want to display, including:

• Details about your return and refund policies
• Your support phone number, email, and website
• Links to your terms of service and privacy policy

Presenting this information can increase buyer confidence and minimize cart abandonment.

Configure support and legal policies

From Checkout Settings, add support contact information to your sessions by enabling Contact information. Similarly, add links to your Terms of service and Privacy policy to your sessions by enabling Legal policies. If you require customers to implicitly consent to your legal policies when they complete their checkout, select the Display agreement to legal terms checkbox.

You must add your support contact information and legal policy links in your Public Detail Settings.

The following previews show how Checkout displays a dialog with the support contact information, links to the store legal policies, and information about the payment terms.

Preview of contact information on Checkout.

Preview of legal policies on Checkout.

Configure return and refund policies

Display your return, refund, or exchange policies, by enabling Return and Refund policies. Although businesses that sell physical goods use return policies, businesses that sell digital goods or customized physical goods typically use refund policies. Because they’re not mutually exclusive, you can select both options if your business sells both categories of goods. You can edit your return and refund details, including:

• Whether you accept returns, refunds, or exchanges
• Whether returns, refunds, or exchanges are free or if they’re subject to a fee
• How many days after a purchase you’ll accept returns, refunds, or exchanges
• How customers can return items shipped to them
• Whether you accept in-store returns
• A link to the full return and refund policy
• A custom message

If you accept free returns, refunds, or exchanges, Checkout highlights the policy for customers.

The following previews show how Checkout displays a return policy. In this example, it’s for purchases that can be returned by shipping them or in-store for a full refund (or exchange) for up to 60 days. You can display similar information for refunds.

Preview of return policies on Checkout.

Preview of a policy highlight on Checkout.

Collect a terms of service agreement

Businesses often require their customers to agree to their terms of service before they can pay. This might depend on the type of product or subscription. Checkout helps you collect the necessary agreement by requiring a customer to accept your terms before paying.

Collect terms of service agreement

You can collect a terms of service agreement with Stripe Checkout when you create a Session:

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=2" \
  -d mode=payment \
  --data-urlencode "success_url=https://example.com/success" \
  -d "consent_collection[terms_of_service]=required" \
  --data-urlencode "custom_text[terms_of_service_acceptance][message]=I agree to the [Terms of Service](https://example.com/terms)"

When consent_collection.terms_of_service='required', Checkout dynamically displays a checkbox for collecting the customer’s terms of service agreement. If consent_collection.terms_of_service='none', Checkout won’t display the checkbox and won’t require customers to accept the terms of service. Before requiring agreement to your terms, set your terms of service URL in your public details of your business. Setting a privacy policy URL is optional—Checkout also links to your privacy policy when a URL to your Privacy policy is set in your public details.

After a customer completes checkout, you can verify that the customer accepted your terms of service by looking at the Session object in the checkout.session.completed webhook, or by retrieving the Session using the API. When the terms are accepted, the Session’s consent.terms_of_service field is set to accepted.

You can customize the text that appears next to the checkbox by using custom_text.terms_of_service_acceptance. You need to set consent_collection.terms_of_service='required'. To use your own terms, insert a Markdown link. For example: I agree to the [Terms of Service](https://example.com/terms)

Collect consent for promotional emails

You can send promotional emails to inform customers of new products and to share coupons and discounts. Before doing so, you must collect their consent to receive promotional emails.

Customize payment method reuse agreement and subscription terms

When a session is in either setup or subscription mode, or is in payment mode with setup_future_usage set, Checkout displays a message about reusing the customer’s payment method. The message can include information specific to the selected payment method. You can hide or customize the default text, but not the payment method-specific text.

For a subscription, the custom text can include information such as the following:

• A link to your subscription terms
• A link to your customer portal
• Cancellation mechanisms and policies

Default payment method reuse agreement in subscription mode

To hide the payment method reuse agreement text, set consent_collection.payment_method_reuse_agreement.position='hidden'. Checkout won’t display its default language governing the reuse of the payment method. To set your own text in place of Stripe’s default language, set custom_text.after_submit.message. You can also use custom_text.submit or custom_text.terms_of_service_acceptance to display your own version of this language.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -d "line_items[0][price]=
{{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=subscription \
  --data-urlencode "success_url=https://example.com/success" \
  -d "consent_collection[payment_method_reuse_agreement][position]=hidden" \
  --data-urlencode "custom_text[after_submit][message]=You can cancel your subscription at any time by [logging into your account](https://www.example.com/)"