Skip to content
Nappai Documentation

Stripe Meter Event

This component allows you to record specific usage data for billing purposes in Stripe. It is designed to help you track consumption-based metrics, such as the number of AI tokens used or API calls made, ensuring that your customers are billed accurately based on their actual usage. By using this component, you can integrate your application’s usage data directly with Stripe’s metering system, enabling automated and precise invoicing.

How it Works

The Stripe Meter Event component acts as a bridge between your automation workflow and the Stripe billing platform. When you configure and run this component, it sends a request to Stripe to log a specific amount of usage for a particular customer.

Internally, the component takes the details you provide—such as the type of event (e.g., “AI Tokens”), the customer identifier, and the quantity used—and sends this information to Stripe’s API. Stripe then records this event against the customer’s account. This process ensures that when you generate invoices, the costs reflect the real-time consumption of your services or products. The component also checks if the data was sent successfully and reports the status back to your workflow.

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 the API Key).
  3. In your workflow, select the saved credential in the Credential input field of this node.

Operations

[OMITTED: This component does not have selectable operations.]

Inputs

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

  • Event Name: The name of the billing meter event as configured in Stripe (e.g., ‘ai_tokens_used’). Max 100 chars.
  • Customer ID: Stripe Customer ID (cus_…) to associate with this event.
  • Value: Numeric usage value for the event (e.g., number of tokens consumed).
  • Identifier: Optional unique event ID for deduplication (max 100 chars). Auto-generated by Stripe if omitted.
  • Timestamp: Unix timestamp (seconds). Defaults to current time. Must be within the past 35 days.

Outputs

After the component executes, it provides two key outputs that you can use to verify the action or proceed with further steps in your workflow:

  • Success Status: A true/false value indicating whether the usage data was successfully recorded by Stripe. If this is True, the event was created. If False, there was an error (e.g., invalid customer ID or API key).
  • Stripe Response Data: Detailed information returned by Stripe. In case of success, this contains the event object details. In case of an error, it may contain error messages that help you diagnose the problem.

Output Data Example (JSON)json

{ “object”: “meter_event”, “id”: “me_1234567890”, “amount”: 100, “event_name”: “ai_tokens_used”, “idempotency_key”: null, “livemode”: false, “customer”: “cus_1234567890”, “created”: 1678901234, “metadata”: {} }

Connectivity

This component is typically used in workflows that handle user interactions, service execution, or automated reporting. It should be connected after a process that generates usage (such as an AI service call or an API request) to record that usage. It is often followed by components that handle error checking or final reporting, using the Success Status output to determine if the billing record was created correctly.

Usage Example

Scenario: Billing for AI Token Usage

  1. Trigger: A user generates text using your AI assistant.
  2. Process: Your workflow counts the number of tokens used in that interaction.
  3. Action: You connect the Stripe Meter Event component to this workflow.
    • Event Name: Set to ai_tokens_used.
    • Customer ID: Pass the ID of the user who made the request.
    • Value: Pass the count of tokens used (e.g., 500).
  4. Result: The component sends this data to Stripe. You can then use the Success Status output to confirm the billing event was logged, ensuring the user is charged correctly for their token consumption.

[OMITTED: No related components listed.]

Important Notes

[OMITTED: No user notes provided.]

Tips and Best Practices

  • Verify Customer IDs: Ensure that the Customer ID you pass is valid and exists in your Stripe account. Invalid IDs will cause the event to fail.
  • Consistent Event Names: Use the exact same Event Name in the component as you have defined in your Stripe Billing settings. Mismatches will prevent the event from being recorded.
  • Handle Errors: Check the Success Status output in subsequent workflow steps. If it returns False, consider adding a step to log the error or notify your team so you can investigate the billing issue.
  • Use Idempotency: If you are unsure if an event was already sent, use the Identifier field with a unique key. This helps prevent duplicate billing events if the workflow retries.

Security Considerations

  • API Key Security: Never hardcode your Stripe API Key directly into the workflow. Always use the Credential feature in Nappai to securely store and reference your API key.
  • Data Privacy: Ensure that the Customer ID and any metadata you send do not include sensitive personal information unless necessary and compliant with your security policies.