Put a scope check in front of your billing browser job

A billing collection job can download a perfectly valid PDF from the wrong place. File checks will not catch that mistake if the document belongs to another product, organization or reporting period.

OpenAI is a useful example. Its billing help distinguishes ChatGPT billing from API-platform billing. Sharing a brand or a login identity does not turn them into one billing workspace.

This post adapts our OpenAI API invoice workflow guide into an application-side design. It does not demonstrate an authenticated account or a working portal collector. The small guard below compares supplied scope observations; it does not verify a login or retrieve an invoice.

Give the request an identity before opening the browser

A request such as “download last month's OpenAI invoices” leaves several decisions implicit. Specify the product, approved account reference, date basis and period before the task starts. Resolve “last month” once at request creation, using the finance team's agreed timezone.

Keep the approved scope separate from the observation made after login. If the same code fills both from the currently selected workspace, a comparison will always succeed, even when the workspace is wrong.

Use a non-secret account reference in logs. Credentials, session cookies and access tokens belong in the authorized credential mechanism, not in the manifest or exception report.

A small guard with a narrow responsibility

The following local data model is illustrative. Its field names are not OpenAI API parameters or a BrowserAct Bot input schema.

from dataclasses import dataclass
from datetime import date

@dataclass(frozen=True)
class Scope:
    product: str
    account_ref: str
    date_basis: str
    start: date
    end_exclusive: date

def require_same_scope(expected: Scope, observed: Scope) -> None:
    for scope in (expected, observed):
        if not scope.product or not scope.account_ref or not scope.date_basis:
            raise ValueError("incomplete scope")
        if scope.start >= scope.end_exclusive:
            raise ValueError("empty or reversed period")
    if expected != observed:
        raise ValueError("scope mismatch; stop before retrieval")

An approved scope might use your application's label openai_api, an account reference mapped to the authorized organization, invoice_date, and an explicit calendar interval. The observation must be grounded in the current page and selected filters. Mapping a displayed organization name to an approved reference needs its own reliable rule; this function cannot discover that mapping for you.

The comparison intentionally fails on any difference. A mismatch is a reason to inspect the request or selected workspace, not permission to silently rewrite the expected value.

Keep permission and availability separate

A matching scope does not establish that the current identity can view every required document. Check permissions and the visible billing history independently. OpenAI's help identifies API organization owners as the route to API billing details; do not generalize that into a claim that any signed-in user can retrieve the same records.

An empty listing also deserves a specific outcome. It could reflect an incorrect scope, unavailable history, insufficient access or an expected set that needs review. Do not manufacture an invoice from usage totals or substitute another product's receipt to make the job appear complete.

If the portal needs renewed login or human confirmation, pause the affected route and retain the approved scope. A successful confirmation should resume the intended job, rather than creating a new request with a different organization selected.

Validate the handoff after retrieval

Scope checks belong before retrieval; reconciliation belongs after it. Match the files against the expected document list and retain the relevant product, organization reference, document identifier and retrieval time.

A generated export link is an intermediate result. Confirm that the authorized file is saved in the intended archive and that its contents match the expected document. Keep invoice documents, receipts and usage summaries distinguishable when the finance process treats them differently.

On a repeat run, use the same approved scope and explicit version policy. An existing filename is not enough to establish either a duplicate or a newer document. Record unresolved items and their reasons so the next operator can continue without repeating the whole month.

BrowserAct's browser workflows are one possible execution route to evaluate. Whatever tool performs the navigation, the application should preserve the request identity from approval through the final file register. A scope guard is a small control, but it prevents one class of wrong result from being mistaken for a successful download.