Skip to main content

Stripe query tutorial

Learn how to query Stripe data in Retool, including auto-pagination and common payment operations.

After setting up a Stripe integration with Retool, your Stripe resource is available to use in the query editor. Retool derives available operations from Stripe's own OpenAPI spec, so the query editor exposes the same requests as Stripe's API.

Create a query​

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

To create a Stripe query in a Retool app:

  1. In the Retool app IDE, open the Code tab, then click + in the page or global scope.
  2. Select Resource query.
  3. Choose your Stripe resource.
  4. Select an operation and configure its parameters.

Query configuration fields​

Stripe queries are operation-driven: selecting an operation determines which parameters and request body fields appear. Refer to the Stripe API reference for the full list of available operations and their parameters. Retool exposes the following configuration fields on top of the operation-specific parameters.

Operation​

The Stripe API operation to run, such as retrieving a list of customers or creating a refund. Selecting an operation loads its specific parameters and, for operations with a request body, a request body editor.

Examples
GET /v1/customers
POST /v1/charges
POST /v1/refunds

Parameters and request body​

Fields shown here come directly from the selected operation's definition in Stripe's API and vary by operation. Use embedded expressions to populate them dynamically from components or other queries.

Example: creating a customer
{
  "name": {{ nameInput.value }},
  "email": {{ emailInput.value }},
  "description": {{ descriptionInput.value }}
}

If you use Stripe Connect, some operations expose a Stripe-Account header parameter. Set it to the account ID of the connected account you want the request to act on behalf of.

Auto-paginate​

Stripe is the only Retool integration that supports automatic pagination. For GET operations that return a list, enable Auto-paginate to have Retool fetch every page of results and return them as a single combined response, instead of requiring server-side pagination in your app.

☐ Auto-paginate

Limit​

Appears when Auto-paginate is enabled. The maximum number of records to fetch across all pages.

Example
500
Best practice

Auto-pagination issues additional requests behind the scenes to collect every page, so set Limit to a value appropriate for the data you need rather than leaving it unbounded, especially for large datasets like charges or events.

Common use cases​

The following examples demonstrate typical Stripe operations in Retool apps. For a complete reference of available operations and parameters, refer to the Stripe API documentation.

list and display customers

First, create a query using the GET /v1/customers operation. Enable Auto-paginate if your account has more customers than fit on a single page.

Example parameters
limit: 100

Next, add a Table component to the app and set its Data property to {{ listCustomersQuery.data.data }}.

create a new customer

First, add a Form component (form1) with input fields for customer data.

Next, create a query using the POST /v1/customers operation.

Example parameters
{
  "name": {{ form1.data.name }},
  "email": {{ form1.data.email }},
  "description": {{ form1.data.description }}
}

Then, add an event handler to the form's Submit event that runs the create customer query and displays a success notification.

create a charge

First, add a Form component with fields for a payment amount and a payment source or method.

Next, create a query using the POST /v1/charges operation. Stripe amounts are in the currency's smallest unit, so multiply a dollar amount by 100 to get cents.

Example parameters
{
  "amount": {{ amountInput.value * 100 }},
  "currency": "usd",
  "customer": {{ customerSelect.value }},
  "description": {{ descriptionInput.value }}
}

Then, add an event handler to the form's Submit event that runs the query and refreshes any charge list on the page.

issue a refund

First, add a Button component in a table of charges to trigger refunds.

Next, create a query using the POST /v1/refunds operation.

Example parameters
{
  "charge": {{ table1.selectedRow.data.id }},
  "amount": {{ refundAmountInput.value * 100 }}
}

Then, add an event handler to the button's Click event:

  1. Action: Show confirmation modal.
  2. If confirmed, trigger the refund query.
  3. Then refresh the charges list.
cancel a subscription

First, add a Button component in a table of subscriptions.

Next, create a query using the DELETE /v1/subscriptions/:subscription_exposed_id operation, with the path parameter set dynamically.

Example path parameter
subscription_exposed_id: {{ table1.selectedRow.data.id }}

Then, add an event handler to the button's Click event:

  1. Action: Show confirmation modal.
  2. If confirmed, trigger the cancel subscription query.
  3. Then refresh the subscriptions list.

Best practices​

Follow these best practices to keep Stripe queries fast, efficient, and safe.

Performance​

  • Enable auto-paginate for complete list operations: Use Retool's Auto-paginate setting instead of building manual pagination logic for GET list operations.
  • Cache responses: For data that doesn't change frequently, enable query caching to reduce API calls and improve response times.
  • Set a reasonable limit: When using auto-pagination, set Limit to the smallest value that satisfies your use case to avoid fetching more records than you need.
  • Minimize payload size: Request only the fields you need by using Stripe's expand parameter selectively rather than expanding every related object.
  • Set appropriate timeouts: Configure query timeouts based on expected API response times to prevent hung requests.

Data integrity​

  • Validate user input: Sanitize and validate all user input before including it in a query to prevent injection attacks.
  • Handle errors gracefully: Configure error notifications and fallback behavior for failed queries to improve user experience.
  • Use idempotency keys: Stripe supports idempotency keys on write operations. Include one to prevent duplicate charges, refunds, or subscriptions if a query is retried.
  • Verify responses: Check response status codes and validate response data structure before using it in your app.
  • Implement retry logic: For transient failures, use Retool's automatic retry settings or implement custom retry logic with exponential backoff.
  • Log query activity: Enable query logging to track requests and responses for debugging and auditing.