Private preview

Define configuration, custom input, and custom output Private preview

Define fields that your users set in the Stripe Dashboard and output values your action returns.

You can ask users of your scripts for values that your script can use at runtime. This lets you change script behavior without rebuilding and redeploying. You can also define output values that downstream workflow steps can reference.

There are two kinds of input you can collect from users:

• Configuration : Values set once when a user activates your extension, available at every runtime.
• Custom input : Values provided each time a user configures an action step in a workflow.

Custom actions can also declare an output schema:

• Custom output : Values your action returns at runtime for downstream workflow steps to reference.

Define configuration

When a user activates an extension, you can ask them for values that your script can use at runtime. These values are passed to your script’s methods in the config argument. For example, a billing extension for prorations might ask users to set a maximum proration amount. A custom action that sends email might ask which of the preconfigured email templates to use.

1. You add properties to your config interface in your extension’s src/index. ts .
2. When you build or upload your app, Stripe converts the interface into a JSON schema stored in generated/config. schema. json .
3. When a user sets up your extension, a form with these fields appears in the Dashboard UI. The user provides static values as input to this form.
4. At runtime, Stripe passes the user-provided values to your script’s methods in the config argument so that you can use them in your custom logic.

Each property has a data type. Stripe renders a specific UI control for each type and applies default validations. You can add additional validation rules using TSDoc annotations.

Add fields to your config interface

This example adds description as a string data type to the config interface.

interface MyExtensionConfig extends Record<string, unknown> {
 description: string;
}

You can then add TSDoc annotations to set validation rules. Stripe enforces these rules when the user submits the form.

interface MyExtensionConfig extends Record<string, unknown> {
 /**
 * @displayName Description
 * @minLength 1
 * @maxLength 50
 */
 description: string;
}

Supported types for configuration

You can use standard TypeScript types such as string, number, and boolean. Import Stripe-specific types such as MonetaryAmount, Percent, Time, and Decimal from @stripe/extensibility-sdk.

Each type has its own set of available TSDoc validators:

The following image shows how the Dashboard renders the different supported data types. The example also shows how validations like maximum character length for the string field and maximum value for the number field appear.

Define custom input

Some extension points let you define a custom input schema. Unlike configuration, which is set once at activation, custom input is provided each time a user configures an action step in the workflow builder. This lets you request input that’s specific to each workflow, for example, which email template to use. These values are passed to your execute method at runtime as request.customInput.

Custom actions only

Only the Workflows custom action extension point supports custom input. Billing extension points don’t use custom input.

You define custom input by adding JSON files to your extension’s src/ directory:

• custom _ input. schema. json required : A JSON Schema that defines the fields and their types
• custom _ input. ui. schema. json optional : A UI schema that controls how the fields render in the workflow builder (layout, dynamic selects, conditional visibility). If you don’t provide a UI schema, the form renders each field as a standard control based on its JSON Schema type. Add a UI schema when you need a custom layout, dynamic selects, dynamic schemas, or field options like multiline text areas.

Define the input schema

Create custom_input.schema.json in your extension’s src/ directory. This defines the fields and their types using JSON Schema:

Define the UI schema optional

If you need a custom layout, dynamic selects, or field options, create custom_input.ui.schema.json in the same directory. This controls the layout and rendering of your fields in the workflow builder. You must add a Control element for each field you want to display. Fields without a corresponding control don’t appear in the UI:

{
 "type": "VerticalLayout",
 "elements": [
 {
 "type": "Control",
 "scope": "#/properties/name"
 },
 {
 "type": "Control",
 "scope": "#/properties/description"
 }
 ]
}

Use "format": "dynamic_select" in the element’s options to render a field as a dropdown populated by get_form_state.

Reference in the manifest

Add the schema files under methods.execute.custom_input in stripe-app.yaml. The input_schema is required. The ui_schema is optional—include it only if you create a UI schema file:

Access custom input at runtime

Stripe passes custom input values to your execute method in request.customInput:

execute(
 request: Extend.Workflows.CustomAction.ExecuteCustomActionRequest,
 _config: MyCustomActionConfig,
 _context: Context
) {
 const input = request.customInput ?? {};
 const name = input.name;
 const description = input.description;

 // Use these values in your action logic
 return {};
}

Make custom input fields dynamic by using the get_form_state method, which populates dropdown options and controls field visibility based on user selections.

Define custom output

Custom actions can return output values that downstream workflow steps reference. Define a custom output schema to declare what your action returns.

Custom actions only

Only the Workflows custom action extension point supports custom output. Billing extension points don’t use custom output.

Add a custom_output.schema.json file to your extension’s src/ directory:

Supported types are: string, boolean, integer, object, and array (array items must be string, boolean, or integer).

Reference in the manifest

Add the output schema under methods.execute.custom_output in stripe-app.yaml:

Return output at runtime

Return a custom_output object from your execute method:

execute(
 request: Extend.Workflows.CustomAction.ExecuteCustomActionRequest,
 _config: MyCustomActionConfig,
 _context: Context
) {
 const input = request.customInput ?? {};

 // ... action logic ...

 return {
 custom_output: {
 messages_sent: 150,
 campaign_id: "camp_abc123",
 },
 };
}

Behavior

• Only fields declared in the output schema are passed to downstream steps. Extra fields are dropped.
• If your schema declares a field but your response doesn’t include it, downstream steps see it as null .
• Returning {} or omitting custom _ output entirely is valid—the action succeeds with no output values.
• A type mismatch (for example, schema declares integer but you return a string) fails the action with a non-retryable error.
• null values are accepted for any declared type.

See also

• Create the schemas
• Build a custom action with a script
• Build a custom action with a remote function