> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.paid.ai/v-2/llms.txt
> - v1: https://docs.paid.ai/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paid.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paid.ai/_mcp/server.

# Backdated order activation

> Understand how Paid backfills credits, invoices, and historical usage when activating orders that started in the past.

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

| Backfill               | What you get                                                                                                 | What's automatic                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Credit grants**      | One credit allocation per elapsed billing period, anchored to `Order.startDate`.                             | All grants are created at activation. Historical and current periods are treated the same. |
| **Invoices**           | One invoice per elapsed billing period.                                                                      | The most recent invoice is auto-posted. Older invoices stay in DRAFT for manual review.    |
| **Historical signals** | Pre-activation usage events for the order's customer + product are replayed against the just-created grants. | Replay runs automatically as part of activation, in chronological order.                   |

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](/documentation/credits/how-credit-balances-work)
* [Understanding the credit ledger](/documentation/credits/understanding-the-credit-ledger)
* [Examples of plans with included credits](/documentation/credits/examples-of-plans-with-included-credits)