Resolve the workspace before reusing a billing-role snapshot

A billing request says “the company workspace.” The worker has several workspaces with similar names and remembers that one operator was an owner during an earlier session. It chooses the familiar name and reports that no invoice is available.

That result may describe the wrong workspace or an outdated role observation.

I work on BrowserAct. Our Notion invoice guide emphasizes that plans belong to individual workspaces and that workspace ownership matters for billing access. It also keeps the documented upcoming-invoice view separate from an unverified historical-PDF export. Those limits suggest a useful application boundary: resolve the exact workspace and assess the age of the identity observation before a billing lookup begins.

This article implements that boundary with synthetic records. It does not authenticate to Notion, inspect a customer's workspace, call a billing API, retrieve invoice files, or test a BrowserAct Bot.

Give the finance request a stable workspace reference

Display names help an operator recognize a workspace. They make fragile database keys: names can change, and different workspaces can look similar. An email address also does not identify which workspace owns a subscription charge.

Use a stable internal workspace reference in the request. Maintain an explicitly reviewed mapping between that reference and the supplier workspace. The example does not assume a particular Notion endpoint exposes this mapping or that a page title proves it.

The same principle applies to the operator. An internal actor reference should map to the authorized identity used for the task. Keep credentials and session tokens outside the observation record. The data below needs identity evidence, not secrets copied into a job log.

Store an observation, not a permanent owner flag

A role observation has a timestamp, an actor, a workspace, and supporting evidence. It should not become a timeless boolean such as has_billing_access = True attached to the entire login.

Workspace membership or ownership can change. Switching to another workspace can also invalidate what the worker previously observed. A recent observation reduces uncertainty but does not guarantee that authorization remains unchanged at the moment of use.

The freshness limit below is an application policy supplied by the caller. It is not a Notion session lifetime or a vendor promise. Set it according to the workflow's review requirements, and recheck after a relevant navigation, role, or identity change even if the time limit has not expired.

from datetime import datetime, timedelta def workspace_review(workspace_ref, actor_ref, observations, now, max_age_minutes): if any(not isinstance(v, str) or not v.strip() for v in (workspace_ref, actor_ref)): raise ValueError("Resolve workspace and actor references") if (type(max_age_minutes) is not int or max_age_minutes <= 0 or now.tzinfo is None or now.utcoffset() is None): raise ValueError("Use an aware clock and positive freshness policy") matches = [o for o in observations if o.get("workspace_ref") == workspace_ref and o.get("actor_ref") == actor_ref] if len(matches) != 1: return "identity_review_required" observation = matches[0] if observation.get("identity_verified") is not True: return "identity_review_required" evidence = observation.get("evidence_ref") if not isinstance(evidence, str) or not evidence.strip(): return "identity_review_required" observed_at = datetime.fromisoformat(observation["observed_at"]) if observed_at.tzinfo is None or observed_at.utcoffset() is None: raise ValueError("Observation timestamp must include its timezone") age = now - observed_at if age < timedelta(0) or age > timedelta(minutes=max_age_minutes): return "refresh_identity_observation" if observation.get("role") != "owner": return "owner_review_required" return "ready_for_billing_lookup_review" 

The function matches references exactly and does not fall back to a display-name search. Duplicate matching observations ask for review instead of silently choosing the newest one. The caller should supply one selected current observation from its history while retaining older evidence separately.

Timezone-aware timestamps allow two equivalent instants with different UTC offsets to compare correctly. A future observation is rejected as a clock or data-quality issue. The policy boundary is inclusive: an observation exactly at the allowed age is accepted by this example.

Keep the readiness result narrow

ready_for_billing_lookup_review says that one supplied observation passed these checks. It grants no role and proves no server-side authorization. The actual service remains responsible for enforcing permissions, and the operator must still verify the current billing context.

The identity_verified field is another trust boundary. A qualified observer must establish it from the real workspace and actor. Copying the expected references into an observation and setting the flag would make the gate meaningless.

The source guide's documented invoice view concerns an upcoming invoice. Even with a fresh owner observation, this code cannot turn that view into proof that historical supplier-original PDFs were downloaded. Keep requested period, purchase type, and actual artifact evidence in separate fields.

Test the reasons a familiar workspace can be wrong

Local synthetic checks cover these cases, strict boolean flags, timezone offsets, and the freshness boundary. They do not validate a vendor role, prove invoice access, or establish a bulk-download path.

For an unresolved identity, ask the responsible owner to clarify the workspace mapping. For an expired observation, collect fresh evidence through the permitted route. Do not automatically promote a member, change the plan, or cycle through unrelated identities until a billing page appears.

Notion plan purchases and credits can require separate document tracking in the source guide. Resolving a workspace does not establish that one invoice covers every purchase. A useful handoff preserves the exact workspace, actor observation, purchase context, and what was actually obtained.

The next worker should be able to explain why this workspace was selected without relying on the previous worker's memory.

Source and native retrieval context: Find Notion invoices for the correct workspace.