Backdated order activation

A “backdated activation” is what happens when you activate an order whose startDate is earlier than the moment you flip it to active. This is normal for historical migrations, contracts that began before they were configured in Paid, and “we’ve been live since X” onboardings. Paid handles it by backfilling three things at activation: credit grants, invoices, and historical signals. This page explains what each of those means, what is auto-finalized vs. left for review, and what does not happen.

What gets backfilled

The rest of this page documents each of these in detail and the cases where backfill does not apply.

Credit grants

Credit allocations are issued for every elapsed billing period from Order.startDate through “now”, inclusive of the current in-flight period.

• Anchor. Periods are anchored to Order.startDate (or the order’s billingAnchor day if you set one explicitly). They are not anchored to the activation date.
• How many. Every full or in-progress monthly cycle from startDate up to the activation moment receives its own grant. For a startDate three months ago on a monthly billing frequency, you get four grants: three completed months and the current one.
• Allocation cadence. With allocationCadence: monthly, each cycle gets one full grant of the configured amount. With allocationCadence: upfront, the full amount is granted at the start of the order’s billing period instead of being spread per month.
• Grant timing. The default is creditGrantTiming: on_order_activation, which is the timing that fires the backfill described here. If a benefit is configured with on_payment, grants are pending until the related invoice is paid. See the “What does not happen” section below.

Note: the entitlement that holds these grants is created with its startDate set to Order.startDate. The grants you see in the credit ledger are the per-period allocations on that entitlement, not the entitlement itself.

Invoice backfill

Activation runs the billing engine across every elapsed cycle, producing one invoice per period.

• One invoice per period. A three-month backdated monthly order produces four invoices: three for the completed historical months, one for the current month.
• Only the most recent is auto-posted. When historical activation is detected, Paid auto-posts the latest draft invoice and leaves older invoices in DRAFT status for manual review. You will see this surfaced in your billing logs as “Historical activation detected; auto-posting the latest draft invoice only and leaving earlier drafts for manual review”.
• The historical drafts are real. They count toward the order’s totalBilledAmount and can be posted manually whenever you’re ready. They are not placeholders.

This split exists because backdated activations frequently mean “we already billed the customer for these periods through some other system”. Auto-posting all the historicals could double-charge.

Historical signal replay

Usage events that were ingested before activation are replayed automatically.

• What qualifies. Signals whose timestamp falls between Order.startDate and the activation moment, attributed to the order’s customer and the product on the order line.
• How replay works. The engine collects these signals in chronological order and decrements the just-created grants period by period. A signal timestamped within a given billing period draws from that period’s grant.
• Signals before Order.startDate are recorded as events but have no grant to draw from. They will not retroactively create earlier grants.

Tip: if your migration involves signals that pre-date the order’s startDate, choose an startDate earlier than your earliest in-scope signal so that replay can attribute them.

Over-consumption

A period’s replayed signals can consume more credits than the period’s grant. Paid records this without blocking activation.

• The used counter on the period’s allocation can exceed total, with the excess captured as overage on the same allocation.
• The allocation status stays ACTIVE. Over-consumption does not flip it to a failure state.
• An overage line is only added to the period’s invoice if the credit benefit is configured with overageUnitPrice > 0. Without overageUnitPrice, the overage is recorded for ledger/audit purposes but is not billed.

This means a backdated activation against a period of high historical usage will reconcile cleanly. You’ll see exactly which periods went over and by how much, and you can decide whether to bill the excess by setting overageUnitPrice on the benefit (in advance) or by issuing a manual invoice (after the fact).

Worked example

You activate today an order with startDate three months ago. The order has one product attribute:

• Monthly subscription: $10/month with a credit benefit of 100 credits/month, allocationCadence: monthly, creditGrantTiming: on_order_activation, no overage unit price.
• A second attribute consumes 10 credits per test_signal event.

Before activation, you sent 40 backdated test_signal events spread evenly across the three-month window.

At activation, Paid:

1. Creates one entitlement anchored to Order.startDate.
2. Issues four monthly credit grants of 100 credits each (months one, two, three, and the current month).
3. Generates four invoices of $10 each. Only the current month’s invoice is auto-posted; the three historical invoices stay in DRAFT.
4. Replays the 40 historical signals chronologically. Each falls into one of the four periods and consumes 10 credits from that period’s grant.

Result:

• The customer’s order shows totalBilledAmount: 40 ($10 × 4 months).
• The credit ledger shows four allocations of 100 credits each. Periods where replayed usage exceeded 100 credits show overage on that period; no overage line is billed because overageUnitPrice is not configured.
• The current period’s allocation has whatever balance is left after the most recent signal decrement.

What does not happen

• Signals timestamped before Order.startDate are not retro-attributed. Signals do not auto-create entitlements; they are recorded as events but do not generate a grant for periods before the order starts. If you need earlier historical signals to count, use an earlier startDate before activating the order.
• Older invoices are not auto-posted. Only the most recent draft is auto-posted; the historical drafts wait for your review.
• on_payment grant timing does not fire at activation. Benefits configured with creditGrantTiming: on_payment issue credits only when the related invoice is marked paid. Activation alone does not grant them.
• Re-activation does not double-grant. Per-period allocations are idempotent on the entitlement’s (startDate, periodStart) key. If you deactivate and re-activate, existing grants are reused, not re-issued.
• Backfill is bounded by Order.startDate. Paid does not grant or invoice for periods before the order’s own start date, even if the product or customer existed earlier.

Related

• How credit balances work
• Understanding the credit ledger
• Examples of plans with included credits