# Add custom fields

Add additional fields to a prebuilt payment page with Checkout.

# Stripe-hosted page

> This is a Stripe-hosted page for when payment-ui is stripe-hosted. View the original doc at https://docs.stripe.com/payments/checkout/custom-fields?payment-ui=stripe-hosted.

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.

Don’t use custom fields to collect personal, protected, or sensitive data, or information restricted by law.

## Create a Checkout Session

Create a Checkout Session while specifying an array of [custom fields](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) parameter to set the language of your Checkout Session to match the same language as your labels.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  SuccessURL: stripe.String("https://example.com/success"),
  CancelURL: stripe.String("https://example.com/cancel"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setSuccessUrl("https://example.com/success")
    .setCancelUrl("https://example.com/cancel")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  success_url="https://example.com/success",
  cancel_url="https://example.com/cancel",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'success_url' => 'https://example.com/success',
  'cancel_url' => 'https://example.com/cancel',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
    },
  ],
})
```

![A checkout page with custom fields](images/checkout/custom-fields/required.png)

## Retrieve custom fields

When your customer completes the Checkout Session, we send a [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) *webhook* with the completed fields.

Example `checkout.session.completed` payload:

```json
{
  "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,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}
```

## 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`.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
            Optional = true,
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  SuccessURL: stripe.String("https://example.com/success"),
  CancelURL: stripe.String("https://example.com/cancel"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
      Optional: stripe.Bool(true),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setSuccessUrl("https://example.com/success")
    .setCancelUrl("https://example.com/cancel")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .setOptional(true)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      optional: true,
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  success_url="https://example.com/success",
  cancel_url="https://example.com/cancel",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
      "optional": True,
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'success_url' => 'https://example.com/success',
  'cancel_url' => 'https://example.com/cancel',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
      'optional' => true,
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      optional: true,
    },
  ],
})
```

![](images/checkout/custom-fields/optional.png)

### 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.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "sample",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Free sample",
            },
            Optional = true,
            Type = "dropdown",
            Dropdown = new Stripe.Checkout.SessionCustomFieldDropdownOptions
            {
                Options = new List<Stripe.Checkout.SessionCustomFieldDropdownOptionOptions>
                {
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Label = "Balm sample",
                        Value = "balm",
                    },
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Label = "BB cream sample",
                        Value = "cream",
                    },
                },
            },
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  SuccessURL: stripe.String("https://example.com/success"),
  CancelURL: stripe.String("https://example.com/cancel"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("sample"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Free sample"),
      },
      Optional: stripe.Bool(true),
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeDropdown)),
      Dropdown: &stripe.CheckoutSessionCustomFieldDropdownParams{
        Options: []*stripe.CheckoutSessionCustomFieldDropdownOptionParams{
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Label: stripe.String("Balm sample"),
            Value: stripe.String("balm"),
          },
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Label: stripe.String("BB cream sample"),
            Value: stripe.String("cream"),
          },
        },
      },
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setSuccessUrl("https://example.com/success")
    .setCancelUrl("https://example.com/cancel")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("sample")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Free sample")
            .build()
        )
        .setOptional(true)
        .setType(SessionCreateParams.CustomField.Type.DROPDOWN)
        .setDropdown(
          SessionCreateParams.CustomField.Dropdown.builder()
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setLabel("Balm sample")
                .setValue("balm")
                .build()
            )
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setLabel("BB cream sample")
                .setValue("cream")
                .build()
            )
            .build()
        )
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'sample',
      label: {
        type: 'custom',
        custom: 'Free sample',
      },
      optional: true,
      type: 'dropdown',
      dropdown: {
        options: [
          {
            label: 'Balm sample',
            value: 'balm',
          },
          {
            label: 'BB cream sample',
            value: 'cream',
          },
        ],
      },
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  success_url="https://example.com/success",
  cancel_url="https://example.com/cancel",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "sample",
      "label": {"type": "custom", "custom": "Free sample"},
      "optional": True,
      "type": "dropdown",
      "dropdown": {
        "options": [
          {"label": "Balm sample", "value": "balm"},
          {"label": "BB cream sample", "value": "cream"},
        ],
      },
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'success_url' => 'https://example.com/success',
  'cancel_url' => 'https://example.com/cancel',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'sample',
      'label' => [
        'type' => 'custom',
        'custom' => 'Free sample',
      ],
      'optional' => true,
      'type' => 'dropdown',
      'dropdown' => [
        'options' => [
          [
            'label' => 'Balm sample',
            'value' => 'balm',
          ],
          [
            'label' => 'BB cream sample',
            'value' => 'cream',
          ],
        ],
      ],
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'sample',
      label: {
        type: 'custom',
        custom: 'Free sample',
      },
      optional: true,
      type: 'dropdown',
      dropdown: {
        options: [
          {
            label: 'Balm sample',
            value: 'balm',
          },
          {
            label: 'BB cream sample',
            value: 'cream',
          },
        ],
      },
    },
  ],
})
```

![A checkout page with a dropdown field](images/checkout/custom-fields/dropdown.png)

### 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`.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "invoice",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Invoice number",
            },
            Type = "numeric",
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  SuccessURL: stripe.String("https://example.com/success"),
  CancelURL: stripe.String("https://example.com/cancel"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("invoice"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Invoice number"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeNumeric)),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setSuccessUrl("https://example.com/success")
    .setCancelUrl("https://example.com/cancel")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("invoice")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Invoice number")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.NUMERIC)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'invoice',
      label: {
        type: 'custom',
        custom: 'Invoice number',
      },
      type: 'numeric',
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  success_url="https://example.com/success",
  cancel_url="https://example.com/cancel",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {"key": "invoice", "label": {"type": "custom", "custom": "Invoice number"}, "type": "numeric"},
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'success_url' => 'https://example.com/success',
  'cancel_url' => 'https://example.com/cancel',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'invoice',
      'label' => [
        'type' => 'custom',
        'custom' => 'Invoice number',
      ],
      'type' => 'numeric',
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'invoice',
      label: {
        type: 'custom',
        custom: 'Invoice number',
      },
      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](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) parameter.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionListOptions { Subscription = "<<subscription>>" };
var service = new Stripe.Checkout.SessionService();
StripeList<Stripe.Checkout.Session> sessions = service.List(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionListParams{Subscription: stripe.String("<<subscription>>")};
result := session.List(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionListParams params = SessionListParams.builder().setSubscription("<<subscription>>").build();

SessionCollection sessions = Session.list(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const sessions = await stripe.checkout.sessions.list({
  subscription: '<<subscription>>',
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

sessions = stripe.checkout.Session.list(subscription="<<subscription>>")
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$sessions = $stripe->checkout->sessions->all(['subscription' => '<<subscription>>']);
```

```ruby
Stripe.api_key = '<<secret key>>'

sessions = Stripe::Checkout::Session.list({subscription: '<<subscription>>'})
```

### Add character length validations 

You can optionally specify a minimum and maximum character length [requirement](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length) for `text` and `numeric` field types.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
            Text = new Stripe.Checkout.SessionCustomFieldTextOptions
            {
                MinimumLength = 10,
                MaximumLength = 20,
            },
            Optional = true,
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  SuccessURL: stripe.String("https://example.com/success"),
  CancelURL: stripe.String("https://example.com/cancel"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
      Text: &stripe.CheckoutSessionCustomFieldTextParams{
        MinimumLength: stripe.Int64(10),
        MaximumLength: stripe.Int64(20),
      },
      Optional: stripe.Bool(true),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setSuccessUrl("https://example.com/success")
    .setCancelUrl("https://example.com/cancel")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .setText(
          SessionCreateParams.CustomField.Text.builder()
            .setMinimumLength(10L)
            .setMaximumLength(20L)
            .build()
        )
        .setOptional(true)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {
        minimum_length: 10,
        maximum_length: 20,
      },
      optional: true,
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  success_url="https://example.com/success",
  cancel_url="https://example.com/cancel",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
      "text": {"minimum_length": 10, "maximum_length": 20},
      "optional": True,
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'success_url' => 'https://example.com/success',
  'cancel_url' => 'https://example.com/cancel',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
      'text' => [
        'minimum_length' => 10,
        'maximum_length' => 20,
      ],
      'optional' => true,
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {
        minimum_length: 10,
        maximum_length: 20,
      },
      optional: true,
    },
  ],
})
```

![A field with character limits](images/checkout/custom-fields/between-validation.png)

### Add default values 

You can optionally provide a default value for the [text](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value), [numeric](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value), and [dropdown](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value) field types. Default values are prefilled on the payment page.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    SuccessUrl = "https://example.com/success",
    CancelUrl = "https://example.com/cancel",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
            Text = new Stripe.Checkout.SessionCustomFieldTextOptions { DefaultValue = "Stella" },
        },
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "size",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Size",
            },
            Type = "dropdown",
            Dropdown = new Stripe.Checkout.SessionCustomFieldDropdownOptions
            {
                DefaultValue = "small",
                Options = new List<Stripe.Checkout.SessionCustomFieldDropdownOptionOptions>
                {
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Value = "small",
                        Label = "Small",
                    },
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Value = "large",
                        Label = "Large",
                    },
                },
            },
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  SuccessURL: stripe.String("https://example.com/success"),
  CancelURL: stripe.String("https://example.com/cancel"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
      Text: &stripe.CheckoutSessionCustomFieldTextParams{DefaultValue: stripe.String("Stella")},
    },
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("size"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Size"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeDropdown)),
      Dropdown: &stripe.CheckoutSessionCustomFieldDropdownParams{
        DefaultValue: stripe.String("small"),
        Options: []*stripe.CheckoutSessionCustomFieldDropdownOptionParams{
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Value: stripe.String("small"),
            Label: stripe.String("Small"),
          },
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Value: stripe.String("large"),
            Label: stripe.String("Large"),
          },
        },
      },
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setSuccessUrl("https://example.com/success")
    .setCancelUrl("https://example.com/cancel")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .setText(SessionCreateParams.CustomField.Text.builder().setDefaultValue("Stella").build())
        .build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("size")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Size")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.DROPDOWN)
        .setDropdown(
          SessionCreateParams.CustomField.Dropdown.builder()
            .setDefaultValue("small")
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setValue("small")
                .setLabel("Small")
                .build()
            )
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setValue("large")
                .setLabel("Large")
                .build()
            )
            .build()
        )
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {
        default_value: 'Stella',
      },
    },
    {
      key: 'size',
      label: {
        type: 'custom',
        custom: 'Size',
      },
      type: 'dropdown',
      dropdown: {
        default_value: 'small',
        options: [
          {
            value: 'small',
            label: 'Small',
          },
          {
            value: 'large',
            label: 'Large',
          },
        ],
      },
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  success_url="https://example.com/success",
  cancel_url="https://example.com/cancel",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
      "text": {"default_value": "Stella"},
    },
    {
      "key": "size",
      "label": {"type": "custom", "custom": "Size"},
      "type": "dropdown",
      "dropdown": {
        "default_value": "small",
        "options": [{"value": "small", "label": "Small"}, {"value": "large", "label": "Large"}],
      },
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'success_url' => 'https://example.com/success',
  'cancel_url' => 'https://example.com/cancel',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
      'text' => ['default_value' => 'Stella'],
    ],
    [
      'key' => 'size',
      'label' => [
        'type' => 'custom',
        'custom' => 'Size',
      ],
      'type' => 'dropdown',
      'dropdown' => [
        'default_value' => 'small',
        'options' => [
          [
            'value' => 'small',
            'label' => 'Small',
          ],
          [
            'value' => 'large',
            'label' => 'Large',
          ],
        ],
      ],
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {default_value: 'Stella'},
    },
    {
      key: 'size',
      label: {
        type: 'custom',
        custom: 'Size',
      },
      type: 'dropdown',
      dropdown: {
        default_value: 'small',
        options: [
          {
            value: 'small',
            label: 'Small',
          },
          {
            value: 'large',
            label: 'Large',
          },
        ],
      },
    },
  ],
})
```

# Embedded form

> This is a Embedded form for when payment-ui is embedded-form. View the original doc at https://docs.stripe.com/payments/checkout/custom-fields?payment-ui=embedded-form.

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.

Don’t use custom fields to collect personal, protected, or sensitive data, or information restricted by law.

## Create a Checkout Session

Create a Checkout Session while specifying an array of [custom fields](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-locale) parameter to set the language of your Checkout Session to match the same language as your labels.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    UiMode = "embedded",
    ReturnUrl = "https://example.com/return",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  UIMode: stripe.String(string(stripe.CheckoutSessionUIModeEmbedded)),
  ReturnURL: stripe.String("https://example.com/return"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setUiMode(SessionCreateParams.UiMode.EMBEDDED)
    .setReturnUrl("https://example.com/return")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  ui_mode="embedded",
  return_url="https://example.com/return",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'ui_mode' => 'embedded',
  'return_url' => 'https://example.com/return',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
    },
  ],
})
```

## Retrieve custom fields

When your customer completes the Checkout Session, we send a [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) *webhook* with the completed fields.

Example `checkout.session.completed` payload:

```json
{
  "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,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "checkout.session.completed"
}
```

## 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`.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    UiMode = "embedded",
    ReturnUrl = "https://example.com/return",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
            Optional = true,
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  UIMode: stripe.String(string(stripe.CheckoutSessionUIModeEmbedded)),
  ReturnURL: stripe.String("https://example.com/return"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
      Optional: stripe.Bool(true),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setUiMode(SessionCreateParams.UiMode.EMBEDDED)
    .setReturnUrl("https://example.com/return")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .setOptional(true)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      optional: true,
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  ui_mode="embedded",
  return_url="https://example.com/return",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
      "optional": True,
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'ui_mode' => 'embedded',
  'return_url' => 'https://example.com/return',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
      'optional' => true,
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      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.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    UiMode = "embedded",
    ReturnUrl = "https://example.com/return",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "sample",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Free sample",
            },
            Optional = true,
            Type = "dropdown",
            Dropdown = new Stripe.Checkout.SessionCustomFieldDropdownOptions
            {
                Options = new List<Stripe.Checkout.SessionCustomFieldDropdownOptionOptions>
                {
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Label = "Balm sample",
                        Value = "balm",
                    },
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Label = "BB cream sample",
                        Value = "cream",
                    },
                },
            },
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  UIMode: stripe.String(string(stripe.CheckoutSessionUIModeEmbedded)),
  ReturnURL: stripe.String("https://example.com/return"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("sample"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Free sample"),
      },
      Optional: stripe.Bool(true),
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeDropdown)),
      Dropdown: &stripe.CheckoutSessionCustomFieldDropdownParams{
        Options: []*stripe.CheckoutSessionCustomFieldDropdownOptionParams{
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Label: stripe.String("Balm sample"),
            Value: stripe.String("balm"),
          },
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Label: stripe.String("BB cream sample"),
            Value: stripe.String("cream"),
          },
        },
      },
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setUiMode(SessionCreateParams.UiMode.EMBEDDED)
    .setReturnUrl("https://example.com/return")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("sample")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Free sample")
            .build()
        )
        .setOptional(true)
        .setType(SessionCreateParams.CustomField.Type.DROPDOWN)
        .setDropdown(
          SessionCreateParams.CustomField.Dropdown.builder()
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setLabel("Balm sample")
                .setValue("balm")
                .build()
            )
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setLabel("BB cream sample")
                .setValue("cream")
                .build()
            )
            .build()
        )
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'sample',
      label: {
        type: 'custom',
        custom: 'Free sample',
      },
      optional: true,
      type: 'dropdown',
      dropdown: {
        options: [
          {
            label: 'Balm sample',
            value: 'balm',
          },
          {
            label: 'BB cream sample',
            value: 'cream',
          },
        ],
      },
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  ui_mode="embedded",
  return_url="https://example.com/return",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "sample",
      "label": {"type": "custom", "custom": "Free sample"},
      "optional": True,
      "type": "dropdown",
      "dropdown": {
        "options": [
          {"label": "Balm sample", "value": "balm"},
          {"label": "BB cream sample", "value": "cream"},
        ],
      },
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'ui_mode' => 'embedded',
  'return_url' => 'https://example.com/return',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'sample',
      'label' => [
        'type' => 'custom',
        'custom' => 'Free sample',
      ],
      'optional' => true,
      'type' => 'dropdown',
      'dropdown' => [
        'options' => [
          [
            'label' => 'Balm sample',
            'value' => 'balm',
          ],
          [
            'label' => 'BB cream sample',
            'value' => 'cream',
          ],
        ],
      ],
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'sample',
      label: {
        type: 'custom',
        custom: 'Free sample',
      },
      optional: true,
      type: 'dropdown',
      dropdown: {
        options: [
          {
            label: 'Balm sample',
            value: 'balm',
          },
          {
            label: 'BB cream sample',
            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`.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    UiMode = "embedded",
    ReturnUrl = "https://example.com/return",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "invoice",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Invoice number",
            },
            Type = "numeric",
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  UIMode: stripe.String(string(stripe.CheckoutSessionUIModeEmbedded)),
  ReturnURL: stripe.String("https://example.com/return"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("invoice"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Invoice number"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeNumeric)),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setUiMode(SessionCreateParams.UiMode.EMBEDDED)
    .setReturnUrl("https://example.com/return")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("invoice")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Invoice number")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.NUMERIC)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'invoice',
      label: {
        type: 'custom',
        custom: 'Invoice number',
      },
      type: 'numeric',
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  ui_mode="embedded",
  return_url="https://example.com/return",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {"key": "invoice", "label": {"type": "custom", "custom": "Invoice number"}, "type": "numeric"},
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'ui_mode' => 'embedded',
  'return_url' => 'https://example.com/return',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'invoice',
      'label' => [
        'type' => 'custom',
        'custom' => 'Invoice number',
      ],
      'type' => 'numeric',
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'invoice',
      label: {
        type: 'custom',
        custom: 'Invoice number',
      },
      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](https://docs.stripe.com/api/checkout/sessions/list.md#list_checkout_sessions-subscription) parameter.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionListOptions { Subscription = "<<subscription>>" };
var service = new Stripe.Checkout.SessionService();
StripeList<Stripe.Checkout.Session> sessions = service.List(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionListParams{Subscription: stripe.String("<<subscription>>")};
result := session.List(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionListParams params = SessionListParams.builder().setSubscription("<<subscription>>").build();

SessionCollection sessions = Session.list(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const sessions = await stripe.checkout.sessions.list({
  subscription: '<<subscription>>',
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

sessions = stripe.checkout.Session.list(subscription="<<subscription>>")
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$sessions = $stripe->checkout->sessions->all(['subscription' => '<<subscription>>']);
```

```ruby
Stripe.api_key = '<<secret key>>'

sessions = Stripe::Checkout::Session.list({subscription: '<<subscription>>'})
```

### Add character length validations 

You can optionally specify a minimum and maximum character length [requirement](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-maximum_length) for `text` and `numeric` field types.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    UiMode = "embedded",
    ReturnUrl = "https://example.com/return",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
            Text = new Stripe.Checkout.SessionCustomFieldTextOptions
            {
                MinimumLength = 10,
                MaximumLength = 20,
            },
            Optional = true,
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  UIMode: stripe.String(string(stripe.CheckoutSessionUIModeEmbedded)),
  ReturnURL: stripe.String("https://example.com/return"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
      Text: &stripe.CheckoutSessionCustomFieldTextParams{
        MinimumLength: stripe.Int64(10),
        MaximumLength: stripe.Int64(20),
      },
      Optional: stripe.Bool(true),
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setUiMode(SessionCreateParams.UiMode.EMBEDDED)
    .setReturnUrl("https://example.com/return")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .setText(
          SessionCreateParams.CustomField.Text.builder()
            .setMinimumLength(10L)
            .setMaximumLength(20L)
            .build()
        )
        .setOptional(true)
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {
        minimum_length: 10,
        maximum_length: 20,
      },
      optional: true,
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  ui_mode="embedded",
  return_url="https://example.com/return",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
      "text": {"minimum_length": 10, "maximum_length": 20},
      "optional": True,
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'ui_mode' => 'embedded',
  'return_url' => 'https://example.com/return',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
      'text' => [
        'minimum_length' => 10,
        'maximum_length' => 20,
      ],
      'optional' => true,
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {
        minimum_length: 10,
        maximum_length: 20,
      },
      optional: true,
    },
  ],
})
```

### Add default values 

You can optionally provide a default value for the [text](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-text-default_value), [numeric](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-numeric-default_value), and [dropdown](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-custom_fields-dropdown-default_value) field types. Default values are prefilled on the payment page.

```dotnet
StripeConfiguration.ApiKey = "<<secret key>>";

var options = new Stripe.Checkout.SessionCreateOptions
{
    Mode = "payment",
    UiMode = "embedded",
    ReturnUrl = "https://example.com/return",
    LineItems = new List<Stripe.Checkout.SessionLineItemOptions>
    {
        new Stripe.Checkout.SessionLineItemOptions { Price = "<<price>>", Quantity = 1 },
    },
    CustomFields = new List<Stripe.Checkout.SessionCustomFieldOptions>
    {
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "engraving",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Personalized engraving",
            },
            Type = "text",
            Text = new Stripe.Checkout.SessionCustomFieldTextOptions { DefaultValue = "Stella" },
        },
        new Stripe.Checkout.SessionCustomFieldOptions
        {
            Key = "size",
            Label = new Stripe.Checkout.SessionCustomFieldLabelOptions
            {
                Type = "custom",
                Custom = "Size",
            },
            Type = "dropdown",
            Dropdown = new Stripe.Checkout.SessionCustomFieldDropdownOptions
            {
                DefaultValue = "small",
                Options = new List<Stripe.Checkout.SessionCustomFieldDropdownOptionOptions>
                {
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Value = "small",
                        Label = "Small",
                    },
                    new Stripe.Checkout.SessionCustomFieldDropdownOptionOptions
                    {
                        Value = "large",
                        Label = "Large",
                    },
                },
            },
        },
    },
};
var service = new Stripe.Checkout.SessionService();
Stripe.Checkout.Session session = service.Create(options);
```

```go
stripe.Key = "<<secret key>>"

params := &stripe.CheckoutSessionParams{
  Mode: stripe.String(string(stripe.CheckoutSessionModePayment)),
  UIMode: stripe.String(string(stripe.CheckoutSessionUIModeEmbedded)),
  ReturnURL: stripe.String("https://example.com/return"),
  LineItems: []*stripe.CheckoutSessionLineItemParams{
    &stripe.CheckoutSessionLineItemParams{
      Price: stripe.String("<<price>>"),
      Quantity: stripe.Int64(1),
    },
  },
  CustomFields: []*stripe.CheckoutSessionCustomFieldParams{
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("engraving"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Personalized engraving"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeText)),
      Text: &stripe.CheckoutSessionCustomFieldTextParams{DefaultValue: stripe.String("Stella")},
    },
    &stripe.CheckoutSessionCustomFieldParams{
      Key: stripe.String("size"),
      Label: &stripe.CheckoutSessionCustomFieldLabelParams{
        Type: stripe.String("custom"),
        Custom: stripe.String("Size"),
      },
      Type: stripe.String(string(stripe.CheckoutSessionCustomFieldTypeDropdown)),
      Dropdown: &stripe.CheckoutSessionCustomFieldDropdownParams{
        DefaultValue: stripe.String("small"),
        Options: []*stripe.CheckoutSessionCustomFieldDropdownOptionParams{
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Value: stripe.String("small"),
            Label: stripe.String("Small"),
          },
          &stripe.CheckoutSessionCustomFieldDropdownOptionParams{
            Value: stripe.String("large"),
            Label: stripe.String("Large"),
          },
        },
      },
    },
  },
};
result, err := session.New(params);
```

```java
Stripe.apiKey = "<<secret key>>";

SessionCreateParams params =
  SessionCreateParams.builder()
    .setMode(SessionCreateParams.Mode.PAYMENT)
    .setUiMode(SessionCreateParams.UiMode.EMBEDDED)
    .setReturnUrl("https://example.com/return")
    .addLineItem(
      SessionCreateParams.LineItem.builder().setPrice("<<price>>").setQuantity(1L).build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("engraving")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Personalized engraving")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.TEXT)
        .setText(SessionCreateParams.CustomField.Text.builder().setDefaultValue("Stella").build())
        .build()
    )
    .addCustomField(
      SessionCreateParams.CustomField.builder()
        .setKey("size")
        .setLabel(
          SessionCreateParams.CustomField.Label.builder()
            .setType(SessionCreateParams.CustomField.Label.Type.CUSTOM)
            .setCustom("Size")
            .build()
        )
        .setType(SessionCreateParams.CustomField.Type.DROPDOWN)
        .setDropdown(
          SessionCreateParams.CustomField.Dropdown.builder()
            .setDefaultValue("small")
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setValue("small")
                .setLabel("Small")
                .build()
            )
            .addOption(
              SessionCreateParams.CustomField.Dropdown.Option.builder()
                .setValue("large")
                .setLabel("Large")
                .build()
            )
            .build()
        )
        .build()
    )
    .build();

Session session = Session.create(params);
```

```node
const stripe = require('stripe')('<<secret key>>');

const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {
        default_value: 'Stella',
      },
    },
    {
      key: 'size',
      label: {
        type: 'custom',
        custom: 'Size',
      },
      type: 'dropdown',
      dropdown: {
        default_value: 'small',
        options: [
          {
            value: 'small',
            label: 'Small',
          },
          {
            value: 'large',
            label: 'Large',
          },
        ],
      },
    },
  ],
});
```

```python
import stripe
stripe.api_key = "<<secret key>>"

session = stripe.checkout.Session.create(
  mode="payment",
  ui_mode="embedded",
  return_url="https://example.com/return",
  line_items=[{"price": "<<price>>", "quantity": 1}],
  custom_fields=[
    {
      "key": "engraving",
      "label": {"type": "custom", "custom": "Personalized engraving"},
      "type": "text",
      "text": {"default_value": "Stella"},
    },
    {
      "key": "size",
      "label": {"type": "custom", "custom": "Size"},
      "type": "dropdown",
      "dropdown": {
        "default_value": "small",
        "options": [{"value": "small", "label": "Small"}, {"value": "large", "label": "Large"}],
      },
    },
  ],
)
```

```php
$stripe = new \Stripe\StripeClient('<<secret key>>');

$session = $stripe->checkout->sessions->create([
  'mode' => 'payment',
  'ui_mode' => 'embedded',
  'return_url' => 'https://example.com/return',
  'line_items' => [
    [
      'price' => '<<price>>',
      'quantity' => 1,
    ],
  ],
  'custom_fields' => [
    [
      'key' => 'engraving',
      'label' => [
        'type' => 'custom',
        'custom' => 'Personalized engraving',
      ],
      'type' => 'text',
      'text' => ['default_value' => 'Stella'],
    ],
    [
      'key' => 'size',
      'label' => [
        'type' => 'custom',
        'custom' => 'Size',
      ],
      'type' => 'dropdown',
      'dropdown' => [
        'default_value' => 'small',
        'options' => [
          [
            'value' => 'small',
            'label' => 'Small',
          ],
          [
            'value' => 'large',
            'label' => 'Large',
          ],
        ],
      ],
    ],
  ],
]);
```

```ruby
Stripe.api_key = '<<secret key>>'

session = Stripe::Checkout::Session.create({
  mode: 'payment',
  ui_mode: 'embedded',
  return_url: 'https://example.com/return',
  line_items: [
    {
      price: '<<price>>',
      quantity: 1,
    },
  ],
  custom_fields: [
    {
      key: 'engraving',
      label: {
        type: 'custom',
        custom: 'Personalized engraving',
      },
      type: 'text',
      text: {default_value: 'Stella'},
    },
    {
      key: 'size',
      label: {
        type: 'custom',
        custom: 'Size',
      },
      type: 'dropdown',
      dropdown: {
        default_value: 'small',
        options: [
          {
            value: 'small',
            label: 'Small',
          },
          {
            value: 'large',
            label: 'Large',
          },
        ],
      },
    },
  ],
})
```

# Embedded components

> This is a Embedded components for when payment-ui is embedded-components. View the original doc at https://docs.stripe.com/payments/checkout/custom-fields?payment-ui=embedded-components.

You can’t add custom fields within the Elements but you can add any additional fields around the Elements or anywhere else on your webpage.