A current billing setup is not a historical document coverage plan

An agency requests six months of billing documents for a client. The worker opens the current billing view and retrieves everything it can see. The folder looks complete until someone notices that the client's billing arrangement changed during the requested period.

The current view was treated as the historical scope.

I work on BrowserAct. Our Google Ads invoice guide describes a separate lookup for documents issued under an earlier billing setup, using the native Billing transfers and previous Invoice setup context. That distinction suggests an application design: plan historical lookup scopes before declaring a collection job ready.

This article implements a small interval check with synthetic data. It does not query Google Ads, discover actual billing-transfer dates, download invoices, or validate an accounting reconciliation. No ad, budget, permission, payment, or billing configuration is changed.

Make a lookup plan before starting retrieval

The plan should identify the client account, the requested document type, and the lookup contexts needed for the requested history. Keep an earlier setup as a separate context instead of replacing its identifier with the current one.

Invoices, statements, payment receipts, and activity exports remain different artifacts in the source guide. A time interval covered by an activity report is not proof that the required invoice files exist. Nor does advertising spend imply that every account receives the same tax document.

For this example, an account owner supplies reviewed historical intervals for one customer and one document-retrieval task. Each interval names a lookup setup and has supporting review evidence. These are proposed application fields, not a Google Ads API response or a guaranteed mapping from setup dates to document dates.

That last boundary matters. A supplier may issue a later correction or place a document somewhere unexpected. A reviewer must decide the lookup plan from actual account evidence; calendar arithmetic cannot decide where every invoice will appear.

Use half-open intervals for the planning boundary

Represent an interval as [start, end): include the first date and exclude the end date. Adjacent scopes can then meet at one boundary without counting the same day twice. For a whole-month request, the end is the first date after the requested period, not the final day at an assumed time of night.

The code below parses calendar dates only. It does not convert payment timestamps, account timezones, service dates, or invoice issue dates. A real implementation must state which date basis its reviewed lookup intervals use.

Do not infer those intervals from the creation time of a local file. Preserve the account evidence and the review reference so another operator can understand why the historical scope was divided.

from datetime import date


def lookup_slices(customer, start, end, history):
    if not isinstance(customer, str) or not customer.strip():
        raise ValueError("Resolve the customer before planning")
    first, stop = date.fromisoformat(start), date.fromisoformat(end)
    if first >= stop:
        raise ValueError("Expected a nonempty requested interval")
    slices = []
    for item in history:
        if item.get("customer") != customer:
            raise ValueError("Mixed customer history needs review")
        if item.get("reviewed") is not True:
            raise ValueError("Unreviewed lookup history")
        if not all(isinstance(item.get(k), str) and item[k].strip()
                   for k in ("setup", "review_ref")):
            raise ValueError("Missing setup or review evidence")
        left = date.fromisoformat(item["start"])
        right = date.fromisoformat(item["end"])
        if left >= right:
            raise ValueError("Invalid historical interval")
        clipped_start, clipped_end = max(first, left), min(stop, right)
        if clipped_start < clipped_end:
            slices.append((clipped_start, clipped_end, item["setup"],
                           item["review_ref"]))
    slices.sort()
    cursor = first
    for left, right, setup, evidence in slices:
        if left < cursor:
            raise ValueError("Overlapping lookup scopes need review")
        if left > cursor:
            raise ValueError("A historical lookup scope is missing")
        cursor = right
    if cursor != stop:
        raise ValueError("The requested history is not fully planned")
    return [{"setup": setup, "start": left.isoformat(),
             "end": right.isoformat(), "review_ref": evidence}
            for left, right, setup, evidence in slices]

The result is a retrieval plan, not a completed archive. The strict reviewed check also rejects truthy strings and integers. It cannot prove that the reviewer was correct or that the supplied evidence is accessible to the worker.

Reject gaps instead of extending the latest setup

Suppose a synthetic request spans January through June. Reviewed context A covers January through March, and context B covers April through June. The output contains two tasks. Reversing the input order produces the same plan.

If context A is absent, the function raises an error. It does not stretch B backwards to January. If A and B overlap, it asks for review rather than choosing whichever entry was most recently added.

Synthetic input	Planning result
Two adjacent reviewed scopes	Two clipped lookup tasks
Request entirely inside one scope	One clipped task
Missing beginning, middle, or end	Validation error
Overlapping or duplicate intervals	Validation error
A different customer mixed into history	Validation error
Missing review evidence	Validation error

These checks establish properties of the supplied plan. They do not establish actual Google Ads document availability, infer a paying-manager relationship, or make the same date basis appropriate for receipts and monthly invoices.

Keep plan coverage separate from file coverage

After planning, each task still needs an authorized retrieval path. The source guide separates native Documents selection, payment receipts, and the monthly-invoicing API route. A working path for one client is not proof that every client can use it.

Keep the requested customer, setup context, document type, document number when known, and artifact evidence together. Record a lookup with no matching document separately from a failed save. Do not convert a successfully planned interval into a “documents complete” flag.

A change to the reviewed history should invalidate the pending plan. Retain the previous version and its observations; review the affected gap before repeating collection. This avoids erasing why an earlier worker searched another setup.

The useful output of the planner is modest: every requested date has an explicitly reviewed lookup context, and no supplied contexts overlap within that request. Actual files, corrections, country-specific requirements, and reconciliation still need their own evidence.

Source and native retrieval context: Download Google Ads invoices, statements and receipts.