Skip to content
Nappai Documentation

Stripe Subscription

This component allows you to manage the lifecycle of customer subscriptions within your Stripe payment system. It acts as a central tool for handling how customers are billed and what services they receive. You can use it to create new subscriptions for customers, check the details of existing ones, list multiple subscriptions at once, modify plan details, or cancel memberships. It is designed to work seamlessly within your Nappai automation workflows to handle recurring billing tasks efficiently.

How it Works

This component connects directly to the Stripe API, a secure external service that processes financial transactions. When you configure this component in Nappai, it sends specific instructions to Stripe based on the inputs you provide.

Internally, the component translates your visual workflow steps into API calls. Depending on the “Mode” you select, it will either fetch a single record by its unique ID or retrieve a list of records based on filters. The component then processes the data from Stripe and returns the results in a structured format (JSON) that you can use in subsequent steps of your automation, such as sending notifications or updating databases.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type Stripe API and fill in the required fields (API Key).
  3. In your workflow, select the saved credential in the Credential input field of this node.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Operation: [DropdownInput]: Selects the type of action the component will perform. Although the interface presents different behaviors, you primarily interact with this component to either retrieve a single record or list multiple records.
  • Mode: [DropdownInput]: Determines how the component behaves. Select “By ID” to retrieve one specific record, or “All” to list multiple records based on filters.
  • Subscription ID: [MessageInput]: The unique ID for a specific subscription (starts with sub_...). This is required when you need to update, cancel, or retrieve a specific subscription record.
  • Customer ID: [MessageInput]: The Stripe Customer ID (starts with cus_...). This is required when you are creating a new subscription or listing all subscriptions for a specific customer.
  • Price ID: [MessageInput]: The Price ID (starts with price_...) that defines the plan and cost. This is required when creating a new subscription.
  • Payment Method ID: [StrInput]: The ID of the payment method to attach to the customer and use for this subscription. For testing purposes, you can use values like pm_card_visa or pm_card_mastercard.
  • Trial Period Days: [IntInput]: The number of days for the free trial period before the first charge is applied.
  • Cancel at Period End: [DropdownInput]: A setting that determines if the subscription should cancel at the end of the current billing cycle.
  • Status Filter: [DropdownInput]: A filter used when listing subscriptions to show only those with a specific status (e.g., Active, Past Due, Canceled).
  • Limit: [IntInput]: The maximum number of records to return when listing subscriptions.

Outputs

  • result: A dictionary containing the detailed data returned from Stripe. This includes subscription details like status, current period dates, and linked customer information.
  • success: A boolean value (True or False) indicating whether the operation completed successfully.
  • error_message: If the operation fails, this field contains a text description of the error. If it succeeds, this is usually empty.
  • response_code: The HTTP status code returned by Stripe (e.g., 200 for success, 400 for client errors).

Output Data Example (JSON)

json { “id”: “sub_123456789”, “status”: “active”, “customer”: { “id”: “cus_987654321”, “name”: “John Doe” }, “plan”: { “id”: “price_xyz123”, “amount”: 2900, “currency”: “usd” }, “current_period_start”: 1678900000, “current_period_end”: 1681500000, “cancel_at_period_end”: false }

Connectivity

This component is typically connected to other nodes in the following ways:

  1. Preceding Components (Inputs): It usually receives data from components that identify customers or prices. For example, a “Retrieve Customer” component might provide the Customer ID, and a “Retrieve Price” component might provide the Price ID or Payment Method ID. These inputs are essential for creating or listing specific subscriptions.
  2. Following Components (Outputs): The output result is often passed to:
    • Notification Components: To send welcome emails or billing confirmations to customers.
    • Database/CRM Components: To save subscription status and ID for record-keeping.
    • Logic/Filter Components: To check the success status or result.status to determine the next step in the workflow (e.g., if active, proceed; if canceled, alert support).

Usage Example

Scenario: Creating a New Subscription for a Customer

  1. Setup Credential: Ensure your Stripe API Key is configured in Nappai.
  2. Configure Inputs:
    • Set Mode to “By ID” if you are checking an existing one, or leave it default for creation/listing context.
    • Enter the Customer ID (e.g., cus_abc123) in the respective field.
    • Enter the Price ID (e.g., price_monthly_premium) for the plan you want to offer.
    • (Optional) Enter a Payment Method ID if you want to attach a specific card.
  3. Execute: The component sends a request to Stripe.
  4. Use Output: Connect the result output to an “Email” component to send a confirmation letter, or to a “Database” component to save the new subscription ID.

Scenario: Listing All Active Subscriptions

  1. Configure Inputs:
    • Set Mode to “All” (or select the listing operation context).
    • Set Status Filter to “Active”.
    • Set Limit to 10 to retrieve the first 10 active subscriptions.
  2. Execute: The component fetches the list.
  3. Use Output: Use the result in a loop component to iterate through each subscription and send renewal reminders.

Tips and Best Practices

  • Use IDs, Not Names: Always use the specific IDs (sub_..., cus_..., price_...) provided by Stripe rather than human-readable names. IDs are unique and prevent errors if names change.
  • Test Payment Methods: When testing in a sandbox environment, use test Payment Method IDs (like pm_card_visa) to avoid actual charges.
  • Handle Errors: Always check the success and error_message outputs in your workflow. If a subscription fails to create due to an invalid payment method, your workflow should know how to handle that failure (e.g., notify an admin).
  • Billing Cycles: Be aware of the Trial Period Days setting. If you set this to 7, the customer won’t be charged for a week. Ensure your downstream notifications account for this delay.

Security Considerations

  • Credential Safety: Never hardcode your Stripe API Key directly in the workflow. Always use the Credential input field to link it securely.
  • API Keys: Ensure you are using the correct type of Stripe API Key (Test vs. Live). Using a Live Key in a testing environment can result in actual charges being made to customer accounts.
  • Data Privacy: The Customer ID and Subscription ID contain sensitive financial associations. Ensure that the outputs of this component are not exposed in logs or notifications that could be viewed by unauthorized users.