Concepts

What it is

By default, the date printed on an invoice is simply the timestamp of when Zenskar generated that invoice. Invoice Date Configuration lets you override that default with a rule instead, so the printed date reflects something more meaningful than "whenever the system happened to run."

A rule works in three stages:

1. Pick a reference date: a known date already tied to the invoice, such as its generation date.
2. Shift it by a fixed offset: move a set number of months before or after that reference date.
3. Pin a day within the resulting month: decide whether to keep the same day number as the reference date, or always land on the last day of that month.

Zenskar applies this rule automatically, every time an invoice is generated, at the organization level. It's a standing policy, not something you set per invoice.

Why it exists

Invoice generation time and billing period rarely need to line up. An invoice might be generated on April 4th but bill for services rendered in March. If the printed date simply reflected generation time, customers' finance teams would see a mismatch between the invoice date and the period it actually covers, forcing them to manually correct dates before reconciling with their own monthly close.

Invoice Date Configuration exists to close that gap. It lets the printed date track the billing period itself, independent of the operational reality of when the invoice document happened to be produced.

For example, an organization might want every invoice to show the last day of the previous month as its date, regardless of when it's actually generated: an invoice generated on April 4 would show March 31.

How the calculation is structured

The rule is built from three independent pieces, each configured separately. Understanding the role each one plays makes it easier to reason about what a given configuration will produce.

Reference date: the starting point

The reference date is what you're calculating from. Zenskar offers three choices, each anchored to a different moment in the invoice's lifecycle:

• Invoice Generation Date (the default): the exact moment Zenskar creates the invoice, in UTC. This is the "no adjustment for billing logic" option, since it ties the date to system behavior rather than to the contract or service period.
• Bill For Date: the date the billing period is anchored to on the contract. This is the right choice when the invoice date should move in lockstep with the billing schedule itself, rather than with operational timing.
• Service Period Start Date: the first day of the service window being billed. Useful when the invoice date should reflect what's actually being charged for, rather than any administrative date on the contract.

Each of these represents a different conceptual anchor: system time, contract schedule, or service delivery. Choosing between them is really a choice about which of those three realities the invoice date should represent.

Offset: shifting away from the anchor

Once a reference date is resolved, the offset moves it forward or backward by a whole number of months. This is what allows the invoice date to represent a different period than the one the reference date sits in, for instance, resolving to the service period's start but then pushing forward a month so the invoice date reflects the period's close instead.

If offset is left off, the calculation simply uses the reference date as-is (subject to day pinning, below).

Day pinning: choosing where in the month to land

The offset determines which month the date falls in; day pinning determines which day within that month:

• Same Day as of Reference Date carries the original day number forward. If the reference date was the 10th, the result is the 10th of the target month.
• Last Day of That Month ignores the original day number entirely and always resolves to the month's final day, useful for "end of period" semantics regardless of which day of the month the reference date happened to fall on.

This two-step separation (month, then day) is what makes the rule flexible: the offset controls timing, and day pinning controls convention (a specific day-of-month vs. a floating "end of month" marker).

Month-end handling

Because day pinning can produce a day number that doesn't exist in the target month (the 31st in a 30-day month, for instance), Zenskar clamps automatically to the closest valid day. Leap years are handled the same way, without any separate configuration.

Worked example

Take an invoice generated on April 4, with the rule set to Invoice Generation Date, offset 1 month before, and Last Day of That Month:

flowchart TD
    A["Reference date: invoice generation
    Resolves to April 4"] --> B["Offset: 1 month before
    Target month becomes March"]
    B --> C["Day pinning: last day of that month
    March's last day is the 31st"]
    C --> D["Printed invoice date
    March 31"]

Each stage narrows the result down: the reference date anchors the calculation to a real moment, the offset moves it to a different month, and day pinning picks the exact day within that month. The same rule produces March 31 no matter which day in April the invoice actually happens to be generated on.

Scope: an organization-wide rule

Invoice Date Configuration is not a per-customer or per-contract setting. It applies uniformly across every invoice in the organization. This is a deliberate trade-off: it keeps the logic predictable and auditable, at the cost of flexibility for edge cases.

If a specific customer or contract genuinely needs a different invoice date, that isn't handled through this configuration at all. It's handled by manually editing the date on that individual invoice (while it's still in draft status). The configuration governs the default behavior for everyone; manual edits are the escape hatch for exceptions.

How this fits together

Put together, the three stages answer three separate questions:

Because these are independent choices, the same reference date can produce very different invoice dates depending on the offset and day pinning selected. That's why it's worth reasoning through each stage separately rather than treating the configuration as a single opaque setting.