Stripe Automation

1. Manage Customers

When to use: User wants to create, update, search, or list Stripe customers

Tool sequence:

1. STRIPE_SEARCH_CUSTOMERS - Search customers by email/name [Optional]
2. STRIPE_LIST_CUSTOMERS - List all customers [Optional]
3. STRIPE_CREATE_CUSTOMER - Create a new customer [Optional]
4. STRIPE_POST_CUSTOMERS_CUSTOMER - Update a customer [Optional]

Key parameters:

• email: Customer email
• name: Customer name
• description: Customer description
• metadata: Key-value metadata pairs
• customer: Customer ID for updates (e.g., 'cus_xxx')

Pitfalls:

• Stripe allows duplicate customers with the same email; search first to avoid duplicates
• Customer IDs start with 'cus_'

2. Manage Charges and Payments

When to use: User wants to create charges, payment intents, or view charge history

Tool sequence:

1. STRIPE_LIST_CHARGES - List charges with filters [Optional]
2. STRIPE_CREATE_PAYMENT_INTENT - Create a payment intent [Optional]
3. STRIPE_CONFIRM_PAYMENT_INTENT - Confirm a payment intent [Optional]
4. STRIPE_POST_CHARGES - Create a direct charge [Optional]
5. STRIPE_CAPTURE_CHARGE - Capture an authorized charge [Optional]

Key parameters:

• amount: Amount in smallest currency unit (e.g., cents for USD)
• currency: Three-letter ISO currency code (e.g., 'usd')
• customer: Customer ID
• payment_method: Payment method ID
• description: Charge description

Pitfalls:

• Amounts are in smallest currency unit (100 = $1.00 for USD)
• Currency codes must be lowercase (e.g., 'usd' not 'USD')
• Payment intents are the recommended flow over direct charges

3. Manage Subscriptions

When to use: User wants to create, list, update, or cancel subscriptions

Tool sequence:

1. STRIPE_LIST_SUBSCRIPTIONS - List subscriptions [Optional]
2. STRIPE_POST_CUSTOMERS_CUSTOMER_SUBSCRIPTIONS - Create subscription [Optional]
3. STRIPE_RETRIEVE_SUBSCRIPTION - Get subscription details [Optional]
4. STRIPE_UPDATE_SUBSCRIPTION - Modify subscription [Optional]

Key parameters:

• customer: Customer ID
• items: Array of price items (price_id and quantity)
• subscription: Subscription ID for retrieval/update (e.g., 'sub_xxx')

Pitfalls:

• Subscriptions require a valid customer with a payment method
• Price IDs (not product IDs) are used for subscription items
• Cancellation can be immediate or at period end

4. Manage Invoices

When to use: User wants to create, list, or search invoices

Tool sequence:

1. STRIPE_LIST_INVOICES - List invoices [Optional]
2. STRIPE_SEARCH_INVOICES - Search invoices [Optional]
3. STRIPE_CREATE_INVOICE - Create an invoice [Optional]

Key parameters:

• customer: Customer ID for invoice
• collection_method: 'charge_automatically' or 'send_invoice'
• days_until_due: Days until invoice is due

Pitfalls:

• Invoices auto-finalize by default; use auto_advance: false for draft invoices

5. Manage Products and Prices

When to use: User wants to list or search products and their pricing

Tool sequence:

1. STRIPE_LIST_PRODUCTS - List products [Optional]
2. STRIPE_SEARCH_PRODUCTS - Search products [Optional]
3. STRIPE_LIST_PRICES - List prices [Optional]
4. STRIPE_GET_PRICES_SEARCH - Search prices [Optional]

Key parameters:

• active: Filter by active/inactive status
• query: Search query for search endpoints

Pitfalls:

• Products and prices are separate objects; a product can have multiple prices
• Price IDs (e.g., 'price_xxx') are used for subscriptions and checkout

6. Handle Refunds

When to use: User wants to issue refunds on charges

Tool sequence:

1. STRIPE_LIST_REFUNDS - List refunds [Optional]
2. STRIPE_POST_CHARGES_CHARGE_REFUNDS - Create a refund [Optional]
3. STRIPE_CREATE_REFUND - Create refund via payment intent [Optional]

Key parameters:

• charge: Charge ID for refund
• amount: Partial refund amount (omit for full refund)
• reason: Refund reason ('duplicate', 'fraudulent', 'requested_by_customer')

Pitfalls:

• Refunds can take 5-10 business days to appear on customer statements
• Amount is in smallest currency unit

Common Patterns

Amount Formatting

Stripe uses smallest currency unit:

• USD: $10.50 = 1050 cents
• EUR: 10.50 = 1050 cents
• JPY: 1000 = 1000 (no decimals)

Pagination

• Use limit parameter (max 100)
• Check has_more in response
• Pass starting_after with last object ID for next page
• Continue until has_more is false

Known Pitfalls

Amount Units:

• Always use smallest currency unit (cents for USD/EUR)
• Zero-decimal currencies (JPY, KRW) use the amount directly

ID Prefixes:

• Customers: cus_, Charges: ch_, Subscriptions: sub_
• Invoices: in_, Products: prod_, Prices: price_
• Payment Intents: pi_, Refunds: re_

Quick Reference

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.