n8n-nodes-usage-billing

This n8n community node provides usage-based billing calculation functionality. It takes usage data and price lists as inputs, performs matching and calculation, and outputs formatted billing records.

IMPORTANT: When updating between versions, make sure to restart your n8n instance after the update. UI changes and new features are only picked up after a restart.

Installation
Features
Operations
Configuration Options
Contributing
Support
License

Features

• Flexible Usage Matching: Match usage data to price list items using multiple fields
• Customer-Specific Pricing: Support for customer-specific pricing rules
• FX Conversion: Convert calculated amounts to a target currency using a fixed exchange rate
• Minimum Sell Price Enforcement: Prevent customer-specific sell prices from falling below the standard pricelist price
• Margin/Profit Calculation: Derive margin, margin %, and markup % from cost and sell amounts
• Pass-Through Fields: Copy billing period dates and identifiers from usage records to output without prefixing
• Calculation Options: Configure rounding and decimal precision
• Output Customization: Control which fields appear in the output with automatic or manual field inclusion
• Usage Summarization: Generate summaries by grouping and totaling fields

Operations

The node provides two main operations:

Match Usage and Calculate

Match usage data with pricing records and calculate costs:

1. Provide price list and usage data in specified fields (supports expressions that return arrays or objects)
2. Configure match fields (productId, region, etc.)
3. Configure calculation options (quantity field, price fields, rounding)
4. Configure customer-specific pricing (if needed)
5. Configure output field options:
   • Automatic mode: Automatically include all fields from both pricelist and usage data with configurable prefixes (default: price_ and usage_)
   • Manual mode: Manually specify which fields to include with custom source and target field names
6. Get calculated billing records as output, with unmatched records in a separate output

Usage Summary

Generate summaries of usage and costs:

1. Provide calculated billing records as input
2. Specify fields to total (cost, price, etc.)
3. Specify fields to group by (date, customer, product, etc.)
4. Get summarized totals as output

Configuration Options

Match Usage and Calculate Configuration

• Price List Field: Field or expression containing price list data (supports arrays, objects, JSON strings, or field paths)
• Usage Data Field: Field or expression containing usage data (supports arrays, objects, JSON strings, or field paths)
• Match Fields: Field pairs to match between price list and usage data (at least one pair required)
• Calculation Configuration: Fields and options for calculation (quantity, cost price, sell price, rounding)
• Customer-Specific Pricing: Options for customer-specific price entries with customer ID matching
• FX Conversion: Enable currency conversion with a fixed exchange rate and target currency code (e.g. USD → AUD at 1.62). Adds calc_fxRate and calc_currencyCode to output.
• Minimum Sell Price Enforcement: When customer-specific pricing is active, ensures the sell price is not lower than the standard pricelist price. Adds minSellEnforced, standardSellPrice, and originalCustomerSellPrice to output when triggered.
• Margin/Profit Calculation: Enable Include Margin Fields in Calculation Settings to add calc_margin, calc_margin_percent, and calc_markup_percent to output. Division-by-zero cases (cost=0 or sell=0) output null.
• Output Field Configuration: Automatic inclusion settings for match fields, calculation fields, and field prefixes
• Pass-Through Fields: In Output Field Configuration, specify a comma-separated list of usage record field names (e.g. startDate,endDate,customerName) to copy verbatim to output without any prefix.
• Output Fields: Control which additional fields to include in output:
  • Automatic Mode: Automatically includes all fields from both pricelist and usage data with required prefixes
  • Manual Mode: Manually specify individual fields with source and target field names

Usage Summary Configuration

• Fields to Total: Comma-separated list of fields to sum
• Group By Fields: Fields to group by when generating summaries
• Include Source Data: Option to include source records in summary

Contributing

Contributions are welcome! If you'd like to contribute to this project:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Support

If you find this node helpful and would like to support its development:

License

MIT