Skip to content

Event-Based Invoice Creation

Certain business events are supposed to produce an invoice right away – an order is activated, a case is closed, a project milestone is completed. Waiting for the next scheduled invoice run is not an option in these scenarios, and creating the invoice manually does not scale.

To this end, JustOn Billing & Invoice Management provides event-based invoice creation – an invocable Apex action that creates the invoice for a single source record, reusing an existing generic invoice run configuration.

The action Create Invoice from GIR (single source) takes the ID of a source record, resolves the matching generic filter, and starts an invoice run for exactly this record – without a scheduled job, without user interaction, and without producing an invoice run record.

You call the action from any Salesforce flow – screen, autolaunched, scheduled, or record-triggered – or from own Apex code:

Event-Based Creation and the Invoice Run

Both mechanisms build the invoice the same way and from the same configuration – they differ in what triggers them and in the scope they process.

Aspect Scheduled invoice run Event-based invoice creation
Trigger A scheduled job, or a user executing the invoice run A business event – via flow or Apex
Scope All records matching the filter and the billing period One source record, passed by the caller
Configuration Generic filter and ON fields The same generic filter and ON fields
Billing period Derived from the invoice run parameters Passed by the caller, defaults to the current month
Invoice run record Created, and linked on the produced invoices None – the invoice's Invoice Run field stays empty
Execution Asynchronous batch chain Asynchronous batch chain
Typical use Recurring and mass billing Immediate billing on a single business event

Info

For mass invoicing of multiple records, the scheduled generic invoice run remains the right tool.

Implementation Details

Invoking the action involves the following steps:

  • The caller passes the ID of the source record – plus, optionally, a filter name, an invoice date and the billing period.

  • JustOn Billing & Invoice Management resolves the generic filter from the object type of the source record.

    A filter name is only required to disambiguate – that is, if the source object has more than one generic filter.

  • JustOn validates the resolved configuration.

    Any configuration problem makes the whole call fail before anything is started (see Error Behavior).

  • JustOn starts an invoice run chain and immediately returns a chain ID for each passed record.

  • The chain creates the invoice and writes its ID back to the ON_Invoice field of the source record.

Info

The processing is asynchronous.

When the flow or the Apex call has finished, the invoice does not exist yet. The process returns the ID of the chain that creates it, not the invoice.

If a subsequent step needs the invoice, track the chain, or read the ON_Invoice field of the source record once the chain has finished.

Chain Grouping

The action does not start one chain per record. Instead, it groups the passed records by

  • the resolved filter,
  • the invoice date,
  • the period start date, and
  • the period end date.

Records that share the same combination collapse into a single chain, while each distinct combination starts its own, separate chain. This makes the action safe to use in bulk record-triggered flows – processing many records starts few chains, not one per record. As a consequence, the result of a bulk invocation may hold multiple different chain IDs – one per group. Logic that builds on the chain ID must therefore handle it per record, not as a single value.

Invoices Produced

  • A single source record may yield several invoices – for example, due to an invoice criterion split, or when invoicing a parent with its child records. The chain handles this in the same way as a regular generic invoice run.
  • Each call creates its own invoices. The action never appends line items to an existing draft invoice.
  • Files attached to the source record are linked to the produced invoice.
  • The produced invoices are ordinary invoices. Finalization and all downstream processing work as with any other invoice.

Duplicate Protection

Re-running the action for the same record is safe. A source record whose ON_Invoice field already references a live – that is, not canceled – invoice is skipped. The call returns a blank chain ID, which is a valid outcome, not an error.

An additional deduplication of invoice line items by their source ID acts as a second backstop.

Info

If the produced invoice is canceled, the source record becomes subject to invoice creation again – consistent with the behavior of the generic invoice run.

Error Behavior

The action distinguishes two different failure situations.

Configuration Error

A configuration error – like a missing or ambiguous filter, or a recurring filter invoked without a billing period – is detected before anything is started. The call fails as a whole, and no chain is started for any of the passed records.

This is an "all-or-nothing" behavior: either every passed record is dispatched, or none is.

Runtime Error

A runtime error during the chain occurs after the dispatch, when the caller has long finished. It is recorded on the ON_InvoiceBuildError field of the source record – exactly as with a regular generic invoice run.

For the individual error conditions and how to handle them, see Create Invoice from GIR.

Specifics to Consider

  • Recurring filters require a billing period.

    Unlike the invoice run UI, the action has no way to have a user confirm a default period. A recurring filter invoked without a period start and end date is therefore rejected – the call fails, rather than silently creating an invoice for an unintended period.

  • The filter is not isolated.

    The filter is an ordinary Generic filter and consequently also available on the invoice run page and via the Invoice Build button. Double billing is prevented by the duplicate protection, not by hiding the filter.

  • No invoice run link.

    The produced invoices have an empty Invoice Run field, and the ON_LastInvoiceRun field of the source record is not set.

    If an object is invoiced by a scheduled generic invoice run as well, use a dedicated transactional suffix for the event-based filter. This keeps the two configurations separate from each other and preserves the audit information of the scheduled run.

  • Permissions

    The action runs in the context of the calling user. This user needs read access to the source records as well as create and edit access to invoices and invoice line items – the same permissions as for the Invoice Build button.