Overview
This node operation, Match Usage and Calculate, is designed to combine usage data with a corresponding price list to calculate cost and sell amounts based on matched records. It is particularly useful in billing or invoicing workflows where you have raw usage data (e.g., product consumption, service usage) and need to apply pricing rules from a price list to compute financial metrics.
Typical scenarios include:
- Telecom or utility companies calculating customer bills by matching usage records with pricing plans.
- SaaS platforms computing charges by matching feature usage against tiered pricing.
- Any business needing to merge transactional usage data with pricing details for accurate cost and revenue calculations.
The node matches records between the price list and usage data using user-defined field pairs that uniquely identify each item. It supports customer-specific pricing when the price list contains entries both general and specific to customers. After matching, it calculates cost and sell amounts optionally applying rounding rules and outputs enriched records combining matched fields and calculated values.
Properties
| Name | Meaning |
|---|---|
| Price List Data | The name of the input field containing the price list data. This must be provided as a single item containing all price list entries. |
| Usage Data | The name of the input field containing usage data. This should be an object with one or more usage records. |
| Match Fields | Pairs of fields used to match records between price list and usage data. Each pair defines which field in the price list corresponds to which field in the usage data. At least one pair is required to ensure unique matching. |
| Customer-Specific Pricing | Configuration to handle cases where the price list has duplicate items differentiated by customer IDs. Includes toggling this feature and specifying the customer ID field names in both price list and usage data. |
| Calculation Settings | Settings controlling calculation behavior: - Quantity Field: field in usage data representing quantity. - Cost Price Field: field in price list for cost price. - Sell Price Field: field in price list for sell price. - Rounding: none, round up, or round down. - Decimal Places: number of decimal places to round to (if rounding applied). |
| Output Field Configuration | Controls which fields are included automatically in output and their naming prefixes: - Include matched price list fields - Include matched usage fields - Include calculation fields (quantity, prices, totals) - Prefixes for price list, usage, and calculation fields - Names for calculated cost and sell amount fields |
| Output Fields | Additional custom fields to include in output records. For each, specify source (price list or usage), source field name, and optional target field name in output. |
Output
The output is an array of JSON objects where each object represents a matched record enriched with calculated fields. The structure includes:
- Matched fields from the price list and usage data, optionally prefixed (e.g.,
price_,usage_). - Calculation-related fields such as quantity, cost price, sell price, and the computed total amounts (
calc_cost_amount,calc_sell_amountby default). - Any additional user-specified fields from either source data.
If rounding is enabled, the calculated amounts respect the specified rounding direction and decimal places.
No binary data output is produced by this operation.
Dependencies
- No external services or APIs are directly required.
- The node relies on correct input data structure: price list data as a single item and usage data as an object with multiple items.
- Proper configuration of matching fields and calculation settings is essential.
- No special environment variables or credentials are needed for this operation.
Troubleshooting
- No Matches Found: If no records match between price list and usage data, verify that the match field pairs correctly correspond to existing fields and that data types align.
- Multiple Matches per Usage Record: Ensure that match fields uniquely identify records; otherwise, multiple matches may cause ambiguous results.
- Missing Fields: If calculation fields like quantity, cost price, or sell price are missing or incorrectly named, calculations will fail or produce incorrect results.
- Customer-Specific Pricing Misconfiguration: When enabled, ensure customer ID fields exist and are correctly named in both datasets to avoid mismatches.
- Rounding Issues: Unexpected rounding results may occur if decimal places or rounding direction are misconfigured.
- Error Messages: Errors thrown are typically related to invalid parameters or data inconsistencies. Review error messages for hints on missing or malformed inputs.
Links and References
- n8n Documentation on Custom Nodes
- General concepts on data matching and billing calculations can be found in billing system design literature and tutorials.