Custom Invoicing

The Custom Invoicing feature enables seamless integration between OpenMeter and external invoicing and payment providers. This advanced functionality requires implementation of custom logic to interface with your chosen external provider after enabling the App.

The integration workflow leverages Invoice Notifications to handle invoice state changes. For invoices managed through the Custom Invoicing App, processing is strategically paused at key states (draft.sync, issuing.sync, payment_processing.pending). Once your integration successfully synchronizes with external systems, it signals completion via the Custom Invoicing APIs, allowing the invoice to progress through its lifecycle.

The overall flow is the following:

#Implementation Guide

To implement custom invoicing functionality, begin by installing the Custom Invoicing App through the OpenMeter Cloud App Marketplace. For self-hosted OpenSource deployments, refer to the Marketplace API Reference for installation instructions.

The Custom Invoicing App provides two configurable synchronization hooks:

• Draft Sync Hook: When enabled, invoice processing pauses at the draft.sync state, requiring your integration to validate and confirm the draft invoice details before proceeding.

• Issuing Sync Hook: When enabled, invoice processing pauses at the issuing.sync state, requiring your integration to verify and confirm the final invoice details before issuance.

Additionally, payment status synchronization is mandatory once an invoice enters the payment_processing.pending state, regardless of hook configurations.

After enabling the app, a Billing Profile must be created referencing the app. We highly recommend to use Customer Overrides to limit the effect of the App instead of making the Billing Profile the default one.

#Basic setup

When no sync hooks are enabled the invoice issuing flow will be the following:

• OpenMeter creates the invoice according Invoice Lifecycle rules
• The invoice reaches payment_processing.pending state, the integration is expected to:
  • send the invoice to the customer
  • initiate and accept payment
  • once the payment has been completed call the App's Update Payment Status to set the payment state

As it's visible the integration is quite straightforward, however this comes at the expense of little control over the flow. The integration is expected to manage the mapping between the OpenMeter Invoice and the external invocing and payments provider IDs and entities.

We are also implicitly expecting that invoice generate by OpenMeter is valid in the external system's representations.

#Advanced: Draft Sync Hook

When the Draft Sync Hook is enabled, invoices will pause at the draft.sync state. At this point, your integration must call the Submit Draft Synchronization Results endpoint to validate the draft and allow the invoice to proceed.

During this synchronization phase, you can perform several key operations:

• Update the invoice number to align with your external system's numbering scheme
• Synchronize the external system's invoice identifier
• Associate external IDs with individual line items and discounts

This synchronization eliminates the need for manual mapping between OpenMeter and external system entities, streamlining the integration process. Additionally, your integration can leverage this state to perform comprehensive invoice validation and, if necessary, make adjustments through the UpdateInvoice endpoint.

#Advanced: Issuing Sync Hook

When the Issuing Sync Hook is enabled, invoices will pause at the issuing.sync state. At this point, your integration must call the Submit Issuing Sync Results endpoint to validate the final invoice details before issuance.

During this synchronization phase, you can perform several key operations:

• Set the external payment identifier to establish a direct link with your payment system
• Perform final validation of the invoice details before sending to the customer
• Ensure all external system requirements are met

This synchronization step provides an additional validation checkpoint and eliminates the need for manual mapping between OpenMeter and your external system entities, further streamlining the integration process.

#Line Mapping Strategies

A critical aspect of the synchronization process is mapping invoice lines to your external billing system. While standalone payment systems can operate solely on invoice totals, proper line item mapping becomes essential when generating detailed invoices or integrating with comprehensive billing platforms.

This section outlines the key strategies for mapping invoice lines between OpenMeter and external systems.

#Aggregate Totals Strategy

The simplest approach is to consolidate all charges into a single line item based on the invoice total. While this method offers straightforward implementation, it has notable limitations:

Advantages:

• Minimal implementation complexity
• Reduced synchronization overhead
• Works well with simple payment processors

Disadvantages:

• Significant loss of itemization detail
• Reduced transparency for end users
• Limited ability to track individual usage components

You should consider using this strategy only in cases where your external system provides limited support for line items, when your users can access detailed usage information through alternative channels, or when you need to prioritize quick implementation over detailed reporting capabilities.

#Grouping

When synchronizing invoice lines with external invoicing systems, it's important to consider the hierarchical structure of usage-based lines and amount discounts.

Usage-based lines function as groupings that contain detailed child invoice lines. For external systems that don't support hierarchical line item structures, integrations can implement a flattening approach by synchronizing only the detailed child lines.

This flattening strategy maintains data integrity since the total amount of a usage-based parent line is mathematically equivalent to the sum of its child line totals and associated discounts.

#Discounts

Amount discounts can be synchronized with external systems using three distinct approaches, each with its own considerations:

The Separate Negative Line Item Approach creates a dedicated line item with a negative value in the external system. This maintains clear visibility of the discount while preserving the original line item amounts. This approach is recommended when the external system supports negative values.

The Native Discount Integration utilizes the external system's built-in discount functionality. This maintains proper categorization of charges versus discounts and preserves reporting capabilities. This approach is optimal when the external system has robust discount support features.

The Line Item Value Adjustment approach involves merging the discount directly into the affected line item. This method adjusts the line item's value to incorporate the discount amount, rather than showing it separately.