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:
- Log in to your Stripe Dashboard at dashboard.stripe.com
- Navigate to Developers → API keys
- 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_
)
- Test mode: Use test keys for development and testing (prefixed with
- Copy the key and paste it in the Appsmith Stripe datasource configuration
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 paidpast_due
- Payment failed but still tryingunpaid
- Payment failed and no longer tryingcanceled
- Subscription canceledincomplete
- Initial payment failedincomplete_expired
- Initial payment failed and expiredtrialing
- In trial periodall
- 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 customerrefund
- Refund to a customerpayout
- Transfer to your bank accountadjustment
- Manual adjustmentstripe_fee
- Stripe's feetransfer
- 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.