Skip to main content

Stripe

This page provides information on how to connect to Stripe. It enables users to perform actions such as creating customers, managing subscriptions, handling products, and accessing balance transactions.

Connect Stripe

To connect to Stripe, you need to authenticate using your Stripe API key. This authentication provides secure access to your Stripe account and resources.

API Key Authentication

To authenticate with Stripe, you need to provide your Stripe secret API key:

  1. Log in to your Stripe Dashboard at dashboard.stripe.com
  2. Navigate to Developers → API keys
  3. Under "Secret key," click "Reveal test key" or "Reveal live key" depending on your environment
    • Test mode: Use test keys for development and testing (prefixed with sk_test_)
    • Live mode: Use live keys for production (prefixed with sk_live_)
  4. Copy the key and paste it in the Appsmith Stripe datasource configuration
note

Consider using restricted API keys with limited permissions for specific use cases

Query Stripe

The following section provides a reference guide describing available commands and their parameters for interacting with Stripe.

Create Customer

Creates a new customer in your Stripe account. This command allows you to define customer details such as email, name, and description, and returns the created customer's information including their unique ID for future reference.

Email Create Customer string

The customer's email address. This is used for communication and helps identify the customer in the Stripe Dashboard.

Email addresses should be valid and properly formatted. Stripe will not validate the email format, but providing a valid email ensures you can contact the customer later.

Example:

customer@example.com

Name string

The customer's full name or business name. This helps identify the customer in the Stripe Dashboard and on invoices.

Example:

John Smith

Description string

Additional information about the customer. This field is for your internal use and is not visible to the customer.

Use this field to store notes or additional context about the customer relationship.

Example:

Enterprise client - Signed up during Q2 promotion

Metadata Create Customer object

A set of key-value pairs that you can attach to the customer. This can be useful for storing additional information about the customer in a structured format.

Metadata is useful for:

  • Storing application-specific information
  • Filtering customers in the Stripe Dashboard
  • Integrating with other systems

Example:

{ "plan_interest": "premium", "referral_source": "google", "account_manager": "jane" }

Get Customer By Id

Retrieves detailed information about a specific customer using their unique Stripe customer ID. This command returns comprehensive data about the customer, including their contact information, payment methods, and subscription status.

Id Get Customer string

The unique identifier of the customer to retrieve.

To find a customer's ID:

  • In the Stripe Dashboard, go to Customers and click on the specific customer
  • The ID appears in the URL as https://dashboard.stripe.com/customers/[CUSTOMER_ID]
  • The ID is also available in API responses from previous customer-related operations

Customer IDs always start with cus_ followed by alphanumeric characters (e.g., cus_1a2b3c4d5e6f).

Example:

cus_1a2b3c4d5e6f

Get Customers

Retrieves a list of customers from your Stripe account based on specified filters. This command returns customer details including their IDs, email addresses, names, and creation dates.

Email Get Customers string

Filters customers based on their email address. This helps you find specific customers when you know their email.

The filter performs an exact match on the email address.

Example:

customer@example.com

Created After integer

Filters customers created after the provided date (Unix timestamp). This helps you find customers who signed up after a specific date.

To convert a date to Unix timestamp:

  • Use a conversion tool or website
  • In JavaScript: Math.floor(new Date('2025-01-01').getTime() / 1000)
  • The timestamp represents seconds since January 1, 1970

Example for January 1, 2025:

1735689600

Created Before integer

Filters customers created before the provided date (Unix timestamp). This helps you find customers who signed up before a specific date.

Example for December 31, 2025:

1767225600

Limit Get Customers integer

Limits the maximum number of customers to return. Defaults to 10 if left blank.

Use this parameter to control the size of the response, especially when you expect a large number of results.

Example:

25

Create Subscription

Creates a new subscription for a customer. This command allows you to subscribe a customer to a specific plan and returns the created subscription's details including its ID, status, and billing information.

Customer Id Create Subscription string

The unique identifier of the customer that the subscription will be created for.

To find a customer's ID:

  • In the Stripe Dashboard, go to Customers and click on the specific customer
  • The ID appears in the URL as https://dashboard.stripe.com/customers/[CUSTOMER_ID]
  • Customer IDs always start with cus_ followed by alphanumeric characters

Example:

cus_1a2b3c4d5e6f

Plan string

The plan that the subscription will be created with. This determines what product and pricing the customer will be subscribed to.

To find a plan's ID:

  • In the Stripe Dashboard, go to Products → Select a product → Pricing
  • The plan ID appears when you click on a specific price
  • Plan IDs typically start with price_ followed by alphanumeric characters

You can use Connect Portal Workflow Settings to allow users to select a plan (example: {{settings.plan}}).

Example:

price_1a2b3c4d5e6f

Metadata Create Subscription object

A set of key-value pairs that you can attach to the subscription. This can be useful for storing additional information about the subscription in a structured format.

Example:

{ "promotion_code": "SUMMER2025", "sales_rep": "alex", "contract_term": "annual" }

Get Subscriptions

Retrieves a list of subscriptions based on specified filters. This command returns subscription details including their IDs, associated customers, plans, statuses, and billing information.

Customer Id Get Subscriptions string

The unique identifier of the customer whose subscriptions you want to list.

To find a customer's ID:

  • In the Stripe Dashboard, go to Customers and click on the specific customer
  • The ID appears in the URL as https://dashboard.stripe.com/customers/[CUSTOMER_ID]
  • Customer IDs always start with cus_ followed by alphanumeric characters

Example:

cus_1a2b3c4d5e6f

Subscription Status string

Filters subscriptions based on their status. This helps you find subscriptions in a specific state.

Valid status values:

  • active - Currently in period and paid
  • past_due - Payment failed but still trying
  • unpaid - Payment failed and no longer trying
  • canceled - Subscription canceled
  • incomplete - Initial payment failed
  • incomplete_expired - Initial payment failed and expired
  • trialing - In trial period
  • all - All statuses

Example:

active

Limit Get Subscriptions integer

Limits the maximum number of subscriptions to return. Defaults to 10 if left blank.

Example:

25

Update Customer

Updates an existing customer's information. This command allows you to modify customer details such as email, name, and description, and returns the updated customer information.

Customer Id string

The unique identifier of the customer to update.

To find a customer's ID:

  • In the Stripe Dashboard, go to Customers and click on the specific customer
  • The ID appears in the URL as https://dashboard.stripe.com/customers/[CUSTOMER_ID]
  • Customer IDs always start with cus_ followed by alphanumeric characters

Example:

cus_1a2b3c4d5e6f

Email Update Customer string

The updated email address for the customer.

Example:

updated.email@example.com

Name string

The updated name for the customer.

Example:

John A. Smith

Description string

The updated description for the customer.

Example:

Enterprise client - Upgraded to premium plan

Metadata Update Customer object

Updated metadata for the customer. This will replace any existing metadata.

Example:

{ "plan_interest": "enterprise", "referral_source": "partner", "account_manager": "sarah" }

Create Product

Creates a new product in your Stripe catalog. This command allows you to define product details such as name and description, and returns the created product's information including its unique ID for future reference.

Product Name string

The name of the product. This appears in the Stripe Dashboard and on customer-facing documents like invoices.

Example:

Premium Subscription

Description string

A description of the product. This helps you and your team identify the product's purpose and features.

Example:

Full access to all premium features with priority support

Metadata Product object

A set of key-value pairs that you can attach to the product. This can be useful for storing additional information about the product in a structured format.

Example:

{ "category": "subscription", "internal_id": "PRO-2025", "feature_set": "complete" }

Get Product By Id

Retrieves detailed information about a specific product using its unique Stripe product ID. This command returns comprehensive data about the product, including its name, description, and associated prices.

Product Id string

The unique identifier of the product to retrieve.

To find a product's ID:

  • In the Stripe Dashboard, go to Products and click on the specific product
  • The ID appears in the URL as https://dashboard.stripe.com/products/[PRODUCT_ID]
  • The ID is also available in API responses from previous product-related operations

Product IDs always start with prod_ followed by alphanumeric characters.

Example:

prod_1a2b3c4d5e6f

Get Balance Transactions

Retrieves a list of balance transactions from your Stripe account. This command returns transaction details including their IDs, amounts, types, and creation dates.

Balance Transaction Type string

Filters transactions based on their type. This helps you find specific types of transactions.

Common transaction types:

  • charge - Payment from a customer
  • refund - Refund to a customer
  • payout - Transfer to your bank account
  • adjustment - Manual adjustment
  • stripe_fee - Stripe's fee
  • transfer - Transfer between Stripe accounts

Example:

charge

Pagination Parameters object

Parameters to control pagination of the transaction list. This allows fetching transactions in batches.

The pagination parameters typically include:

  • limit: Number of transactions to return per page (integer)
  • starting_after: The ID of the last transaction from the previous page (string)
  • ending_before: The ID of the first transaction from the next page (string)

Example for retrieving the next page after a specific transaction:

{
"limit": 25,
"starting_after": "txn_1a2b3c4d5e6f"
}

For initial request:

{
"limit": 25
}

Get Plans

Retrieves a list of plans (prices) from your Stripe account. This command returns plan details including their IDs, associated products, pricing, and billing intervals.

Is Plan Active boolean

Filters plans based on their active status. Set to true to list all active plans or false to list all inactive plans.

Example to list active plans:

true

Example to list inactive plans:

false

Pagination Parameters object

Parameters to control pagination of the plans list. This allows fetching plans in batches.

The pagination parameters typically include:

  • limit: Number of plans to return per page (integer)
  • starting_after: The ID of the last plan from the previous page (string)
  • ending_before: The ID of the first plan from the next page (string)

Example:

{
"limit": 25,
"starting_after": "price_1a2b3c4d5e6f"
}

Get Products

Retrieves a list of products from your Stripe catalog based on specified filters. This command returns product details including their IDs, names, descriptions, and creation dates.

Created After integer

Filters products created after the provided date (Unix timestamp). This helps you find products that were added after a specific date.

Example for January 1, 2025:

1735689600

Created Before integer

Filters products created before the provided date (Unix timestamp). This helps you find products that were added before a specific date.

Example for December 31, 2025:

1767225600

Limit Get Products integer

Limits the maximum number of products to return. Defaults to 10 if left blank.

Example:

25

Custom Action

Executes a custom action against the Stripe API. This command allows for advanced operations not covered by the standard commands.

This command enables you to make custom API calls to Stripe endpoints not covered by the standard commands. You can specify the endpoint, method, and parameters to access additional Stripe functionality.

When using Custom Action, you'll need to refer to the Stripe API documentation for specific endpoint details and required parameters.

Example for a custom query to list events:

GET /v1/events

Example for a custom query to create a coupon:

POST /v1/coupons
{
"percent_off": 25,
"duration": "once"
}

Custom actions require appropriate authentication and permissions for the endpoints being accessed.