Billwerk icon

Billwerk

Automate your subscription business with billwerk

Actions27

Overview

The Billwerk node for n8n enables automation of subscription business processes using the Billwerk API.
Specifically, when configured with the Resource: Metered Usage and Operation: Create, this node allows you to record (book) metered usage for a specific contract and component in Billwerk. This is useful for businesses that bill customers based on variable consumption (e.g., API calls, storage used, minutes consumed).

Practical examples:

  • Automatically log API usage for a customer at the end of each billing cycle.
  • Record the number of units consumed by a user for a pay-per-use service.
  • Integrate with IoT devices to book measured consumption data directly into Billwerk.

Properties

Name Type Meaning
Contract ID String The unique identifier of the contract for which the metered usage is being booked.
Component ID String Billwerk ID of the metered usage component (the item or service being measured).
Quantity Number The amount of usage to be recorded (e.g., number of units consumed).
Memo String Optional short description associated with the usage entry.
Due Date DateTime The date when the metered usage is due (when it should be considered for billing).

Output

The node returns a JSON object representing the result of the metered usage creation operation.
While the exact structure depends on the Billwerk API response, typical fields may include:

{
  "id": "string",             // Unique identifier for the metered usage entry
  "contractId": "string",     // The contract ID associated with the usage
  "componentId": "string",    // The component ID for the metered usage
  "quantity": number,         // The quantity booked
  "memo": "string",           // The memo/description (if provided)
  "dueDate": "string",        // The due date in ISO format
  "status": "string",         // Status of the booking (e.g., 'created', 'pending')
  // ...other fields as returned by Billwerk
}

If an error occurs and "Continue On Fail" is enabled, the output will contain an error field with the error message.

Dependencies

  • External Service: Requires access to the Billwerk API.
  • API Credentials: You must configure valid Billwerk API credentials in n8n under the name billwerkApi.
  • n8n Configuration: No additional environment variables are required beyond standard credential setup.

Troubleshooting

Common Issues:

  • Missing or Invalid Contract/Component ID: Ensure both IDs are correct and exist in your Billwerk account.
  • Invalid Quantity: The quantity must be a positive number; negative or zero values may be rejected.
  • Authentication Errors: If credentials are missing or incorrect, authentication will fail.
  • Date Format Issues: The Due Date must be in a valid datetime format.

Error Messages:

  • "Contract not found": Check that the Contract ID exists in Billwerk.
  • "Component not found": Verify the Component ID is correct and belongs to the contract.
  • "Invalid quantity": Ensure the Quantity is a valid number greater than zero.
  • "Authentication failed": Re-check your Billwerk API credentials in n8n.

Resolution Steps:

  • Double-check all input property values.
  • Review Billwerk API documentation for required formats.
  • Test credentials via another tool if unsure.

Links and References

Discussion