Skip to content
Nappai Documentation

Stripe Invoice

Stripe Invoice

The Stripe Invoice component allows you to manage the complete lifecycle of invoices within your Stripe account. It acts as a central tool for creating, retrieving, updating, and processing billing documents for your customers.

Whether you need to generate a new invoice for a subscription, send a payment link to a client, or track the status of a payment, this component provides the necessary tools to keep your billing data accurate and up-to-date. It integrates directly with the Stripe API, ensuring that your automation system stays synchronized with your actual financial records.

How it Works

This component serves as a bridge between your automation workflows and Stripe’s billing infrastructure. When you use this component, it communicates with Stripe’s servers to perform specific tasks related to invoices.

It operates based on two main concepts:

  1. Resource Type: You choose whether to manage the Invoice document itself or the Invoice Items (the individual line items or charges) that make up the invoice.
  2. Mode of Action: You decide whether to work with a single specific record (using its ID) or to list all records (often filtered by customer or status).

Once you configure these settings, the component sends the request to Stripe. For example, if you create an invoice, Stripe generates a unique ID for it and returns the details back to your workflow. If you update an invoice, Stripe saves those changes and provides the updated status. This ensures that any subsequent steps in your automation (like sending an email or updating a database) use the latest, most accurate financial data.

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 (specifically your 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:

  • Type: Choose between “Invoice” to manage the overall billing document or “Invoice Item” to manage specific line items (charges) within an invoice.
  • Operation: A dropdown menu where you select the action to perform (e.g., Create, Retrieve, Update).
  • Mode: Select “By ID” to retrieve or act on one specific record using its unique ID, or “All” to list multiple records based on filters.
  • ID: The unique Resource ID (e.g., in_...) required for actions like Update, Delete, or fetching a specific invoice. Required when Mode is “By ID”.
  • Customer ID: The Stripe Customer ID (e.g., cus_...) required for creating new invoices or retrieving all invoices for a specific customer.
  • Amount: The charge amount in the smallest currency unit (e.g., cents for USD). Required when creating Invoice Items.
  • Currency: The three-letter ISO currency code (e.g., USD, EUR) for the transaction.
  • Description: A text description of the charge or invoice, visible to the customer on the final document.
  • Collection Method: How the payment should be collected. Options typically include “Charge automatically” or “Send an invoice”.
  • Days Until Due: The number of days until the invoice is due. Required when the Collection Method is set to “Send an invoice”.
  • Footer: Any custom text to appear at the bottom of the invoice document.
  • Status Filter: Used when listing invoices (“All” mode) to filter results by status (e.g., Only “Paid” or “Uncollectible” invoices).
  • Invoice ID: Used when managing Invoice Items to specify which existing invoice (in_...) the item should be attached to. Leave empty if adding to the next upcoming invoice.
  • Limit: A number limiting how many records are returned when using “All” mode.

Outputs

This component returns structured data about the invoice or invoice item you interacted with. The output allows you to pass critical billing information (like total amounts, status, and payment links) to other components in your workflow.

Output Data Example (JSON)json

{ “id”: “in_1234567890”, “status”: “paid”, “total”: 1500, “hosted_invoice_url”: “https://invoice.stripe.com/i/acct_123/test”, “customer”: “cus_1234567890”, “lines”: [ { “amount”: 1000, “description”: “Monthly Subscription” }, { “amount”: 500, “description”: “Tax” } ], “created”: 1672531200 }

Note: The exact fields available in the output depend on the “Type” and “Operation” selected.

Connectivity

This component is typically connected to other parts of a financial or customer management workflow.

  • Connects To:

    • Email/Notification Components: After creating or finalizing an invoice, the output (specifically the hosted_invoice_url or id) can be mapped to email components to send payment reminders or invoices to customers.
    • CRM/Database Components: The Customer ID and Invoice ID outputs are often sent to databases or CRMs to keep customer records updated with their latest billing status.
    • Payment Verification Components: Outputs like status can be used in conditional branches to determine if a payment was successful before proceeding with order fulfillment.

  • Common Predecessors:

    • Stripe Customer: Often, the Customer ID input for this component is mapped from the output of a “Stripe Customer” component to ensure you are billing the correct person.
    • Stripe Subscription: In recurring billing workflows, this component may be triggered by subscription events to generate monthly invoices.

Usage Example

Scenario: Sending an Invoice to a New Customer

  1. Create Invoice Item: Use the “Stripe Invoice” component with Type set to “Invoice Item”. Provide a Customer ID, Amount, and Description.
  2. Finalize Invoice: Use the component again with Type set to “Invoice”. Use Mode “By ID” (if you know the draft invoice ID) or create a new invoice. Select the operation to “Finalize” or “Send”.
  3. Send Email: Connect the hosted_invoice_url output from the “Finalize Invoice” step to an Email Component. The email will contain a link for the customer to pay the invoice securely via Stripe.

Important Notes

📋 Requirement: Credential Setup You must have a valid Stripe API credential configured in Nappai before this component can communicate with Stripe. Ensure your API Key has the necessary permissions for invoices.

⚠️ Limitation: Invoice Deletion You can only delete an invoice if it is in the draft state. Once an invoice is finalized, open, or paid, it cannot be deleted for legal and accounting reasons. Instead, you must use the “Void” operation to cancel it.

💡 Best Practice: Use Status Filters When listing invoices, always use the Status Filter input. Listing all invoices without filtering can result in large data payloads and slow down your workflow. Filter for “Paid” or “Open” invoices to get relevant data quickly.

ℹ️ Behavior: Invoice Items When adding an Invoice Item, you can choose to attach it to a specific existing invoice (Invoice ID input) or let Stripe automatically attach it to the next upcoming invoice for that customer.

Tips and Best Practices

  • Use Mapping Mode for Dynamic Data: When dealing with varying customer amounts, use Mapping Mode to connect the Amount input directly from a previous calculation step or database query, rather than hardcoding fixed values.
  • Check Status Before Updating: Before trying to update or void an invoice, it is good practice to first “Retrieve” the invoice to check its current status. This prevents errors if the invoice has already been paid or voided by another process.
  • Include Metadata for Tracking: When creating invoices, consider using the Metadata field (if available in your specific setup) to store internal order numbers or ticket IDs. This makes it easier to reconcile Stripe invoices with your internal records later.
  • Handle Amounts in Smallest Units: Remember that amounts should be entered in the smallest currency unit (e.g., cents for USD). $10.00 should be entered as 1000.

Security Considerations

  • Secure API Keys: Never expose your Stripe API Key in public repositories or logs. Always use the Credential field in Nappai, which handles secure storage.
  • Invoice Visibility: Invoices often contain sensitive customer data (names, emails, payment details). Ensure that your workflow does not expose these details to unauthorized endpoints. Use secure channels for email notifications and database storage.
  • Idempotency: When creating invoices, ensure your automation handles potential duplicate requests gracefully to avoid creating duplicate charges. Stripe handles idempotency for you if you provide a unique client ID or handle retries correctly in your workflow.