Designing Multi-Tenant APIs for Account-Level Placement Exclusions

Hook: Stop fighting inventory noise — give tenants safe account-level control

Ad ops and platform teams building ad-serving or display-management SaaS in 2026 face the same recurring problem: tenants demand easy controls to block unsafe or low-quality placements, but exposing those controls risks permission leaks, sync conflicts, and broken automation across campaigns. This blueprint shows how to build a multi-tenant API that safely exposes account-level placement exclusions, handles permissioning and validation, syncs with Google Ads’ new account-level exclusion capabilities, and resolves conflicts predictably across campaigns and formats.

Executive summary — what you’ll get from this guide

• Design patterns for a multi-tenant exclusions API that preserves tenant isolation and supports enterprise RBAC.
• Concrete endpoint and data-model examples for account-level exclusions (JSON schema + idempotency tips).
• Strategies for validation, sanitization, and rate-limit-aware Google Ads sync (push/pull + reconciliation).
• Conflict resolution models (precedence rules, merge algorithms) across on-platform campaign settings and Google Ads’ account-level exclusions.
• Operational checklist: audit logs, monitoring, testing, rollout and migration patterns for existing campaign-level blocks.

Context: Why account-level exclusions matter in 2026

Google’s rollout in January 2026 of account-level placement exclusions changed the automation landscape for advertisers. Rather than adding blocks campaign-by-campaign, teams can enforce global inventory blocks across Performance Max, Display, YouTube and Demand Gen campaigns from one centralized setting. That convenience reduces management overhead but increases the need for precise programmatic control from any SaaS that manages advertising accounts.

“Google Ads now lets advertisers block unwanted inventory from a single, centralized setting.” — Search Engine Land, Jan 15, 2026

For SaaS platform teams that synchronize tenant preferences to Google Ads, this creates new responsibilities: ensure tenant changes are safe, permissioned, auditable, and reconciled against both local campaign-level controls and Google’s automation. The rest of this article focuses on practical design and operational guidance for doing that well.

Design principles: Secure, auditable, and deterministic

1. Tenant isolation: Data for tenant A must never influence tenant B. Use tenant-aware partitioning at the DB and API layer.
2. Principle of least privilege: Expose exclusion APIs only to roles that require them. Differentiate between read-only users, exclusion editors, and admins who can enforce org-wide (platform) defaults. For supervised systems and edge governance patterns see Augmented Oversight.
3. Idempotence & eventual consistency: External systems (Google Ads) and your service operate asynchronously — design idempotent endpoints and reconciliation jobs.
4. Deterministic conflict rules: Define clear precedence (platform > account > campaign > ad group) and implement merge strategies so the same inputs produce the same outputs every time.
5. Auditable changes: Every change must be logged with who, when, before/after, and sync status for compliance and troubleshooting. See chain-of-custody patterns for distributed systems at Chain of Custody.

Core data model: what to store for each exclusion

At minimum, track the following fields for each exclusion entry. Keep records small and normalized to make reconciliation cheap.

• exclusion_id (UUID): platform-side primary key
• tenant_id: logical owner
• scope: account | campaign | ad_group (we recommend defaulting to account-level for tenant-exposed API)
• type: placement_url | app_id | youtube_channel | inventory_category
• value: the string value (e.g., example.com/path, com.example.app, UC_xxx)
• status: active | pending_sync | failed | archived
• created_by, updated_by, timestamps
• precedence: integer used when merging conflicting rules
• external_id: ID from Google Ads (if synced)
• metadata: freeform JSON for reasons, tags, or audit notes

API surface — endpoints and contracts

Expose a concise RESTful (or GraphQL) API for exclusions. Below is a recommended REST contract. Replace path segments as needed to fit your routing conventions.

Key endpoints

• GET /tenants/{tenant_id}/exclusions — list exclusions
• POST /tenants/{tenant_id}/exclusions — create exclusion (idempotent)
• GET /tenants/{tenant_id}/exclusions/{exclusion_id} — fetch single
• PATCH /tenants/{tenant_id}/exclusions/{exclusion_id} — update (status, value, precedence)
• DELETE /tenants/{tenant_id}/exclusions/{exclusion_id} — soft-delete / archive
• POST /tenants/{tenant_id}/exclusions/bulk — bulk import, returns per-item result
• POST /tenants/{tenant_id}/exclusions/reconcile — trigger reconciliation with ad accounts

Example create request (idempotent)

{
  "idempotency_key":"uuid-or-client-generated-key",
  "type":"placement_url",
  "value":"example.com/badcontent",
  "scope":"account",
  "precedence":100,
  "metadata": { "reason":"brand_safety", "tags":["publisher_blacklist"] }
}

Important: require an idempotency_key on POSTs to safely retry when a downstream sync fails.

Permissioning and RBAC

Design role-based access controls that reflect real world needs: marketers should be able to propose changes, but approvals may be required for high-impact blocks. Use attribute-based access control (ABAC) in larger orgs.

• Roles: viewer, editor, approver, admin
• Scopes: tenant-scoped, location-scoped (multi-location tenants), and platform-scoped
• Approval workflow: optional workflows for sensitive exclusions (e.g., blocking entire domains or YouTube channels)
• Policy engine: incorporate allow/deny lists for domain patterns (e.g., top-level domains) and business rules

Practical permission patterns

• Allow editors to create proposed exclusions but mark them pending until an approver escalates to active.
• Provide a separate system role for platform/global overrides. These should have explicit, logged consent and higher precedence.
• Implement attribute checks — e.g., prevent tenant editors from creating exclusions that would apply to other tenants or global campaigns.

Validation and sanitization (defense in depth)

Validate client inputs strictly before accepting an exclusion. Sanitization reduces error-prone entries and prevents sync failures with ad platforms.

• Normalize domains to a canonical form (lowercase, remove protocol, strip query strings unless supported).
• Reject wildcard-only domains unless explicitly allowed by policy; prefer explicit hostnames or path segments.
• Validate YouTube channel IDs vs URLs; validate app IDs by platform convention.
• Enforce a max length and a denylist of risky patterns (e.g., IP addresses, private ranges).
• Return granular errors so UI can show which items failed in bulk imports.

Syncing with Google Ads — practical architecture

Google Ads’ 2026 account-level exclusions let you map platform account-level exclusions to Google’s account-level exclusion lists. The simplest reliable architecture uses a push-based sync + periodic reconciliation:

1. Change capture: when a tenant activates an exclusion, enqueue a change event.
2. Worker queue: background job serializes changes, batches them to Google Ads API, respects rate limits, and stores the external_id and response.
3. Reconciliation job: scheduled job (daily + on-demand) compares platform state vs Google Ads state and fixes drift.
4. Webhooks / callbacks: subscribe to Google Ads asynchronous job statuses or use polling if webhooks are unavailable.

Batching & rate limits

• Batch many small exclusion changes into a single Google Ads API call where possible.
• Use exponential backoff for transient 5xx errors; use circuit breakers for sustained failures.
• Honor Google Ads quota by prioritizing tenant changes by SLA class (paid tenants first). See cost and quota patterns in Cloud Cost Optimization.

Idempotency and retries

Attach your own idempotency keys and correlate platform entries with Google Ads external IDs. If a push returns a partial success, store per-item status so reconciliation can complete the work later.

Conflict resolution: predictable and explainable

Conflicts occur when multiple sources specify different exclusions for the same placement: tenant-level vs campaign-level, platform global overrides, or manual changes in Google Ads. Define and implement a conflict model:

Recommended precedence model (highest → lowest)

1. Platform global overrides (emergency blocks) — admin-only
2. Tenant account-level exclusions (exposed via API)
3. Campaign-level exclusions — created by the tenant inside the platform
4. Ad group or creative-level blocks
5. Ad platform manual changes flagged as "external edits" — track and reconcile

Technical patterns to implement precedence:

• Store a precedence integer per exclusion; when constructing consolidated exclusion lists, sort by precedence and deduplicate by placement key.
• When a higher precedence rule blocks a placement, mark lower precedence entries as shadowed rather than deleting them — this preserves intent and audit trail.
• Notify users of shadowing in the UI: e.g., “This campaign-level block is shadowed by an active account-level exclusion.”

Handling external edits in Google Ads

When Google Ads shows a condition that doesn't match platform state (someone edited directly in Google Ads), you have two choices:

• Reconcile to platform: overwrite Google Ads to match platform state (safe if platform is source-of-truth).
• Flag as external: mark the Google change as external and surface it to tenant for approval.

Most SaaS products provide a configurable policy per tenant that chooses behavior. Large enterprises typically prefer explicit notifications and manual reconciliation to avoid surprising automation overwrites.

Tenant isolation and multi-tenant concerns

Multi-tenancy introduces two primary risks: data leakage and cross-tenant side effects when pushing shared lists to ad platforms. Defend against both.

• Per-tenant Google Ads accounts: where possible, map each tenant to a distinct Google Ads account/manager account so account-level Google exclusions are naturally isolated.
• Shared Google Ads account model: if tenants share a Google Ads account, maintain per-tenant exclusion lists locally and compute merged lists per-campaign when pushing. Never push a tenant’s exclusion intended for another tenant. For standards and multi-tenant API integration patterns, consider Open Middleware Exchange approaches.
• Encryption & RBAC: encrypt sensitive metadata at rest and use service accounts with minimal OAuth scopes for Google API access.

Auditing, observability and troubleshooting

Good observability makes operations manageable and supports compliance audits.

• Audit logs: record every API call, who initiated it, payload diff, resulting external IDs, and sync status. Keep logs tamper-evident (append-only or signed entries).
• Sync dashboard: show last sync status per tenant, queued items, failures, and external drift indicators.
• Alerting: alert on persistent reconcile failures, rate limit throttling, and repeated external edits.
• Tracing: propagate request IDs through background jobs for end-to-end traceability. See observability patterns at Observability for Workflow Microservices.

Testing and rollout patterns

Rollouts that touch global inventory controls require careful testing to avoid accidental overblocking. Use canary and staged approaches:

• Staging environment: maintain a non-prod Google Ads test account that mirrors production tenancy; pair with portable lab network kits from field reviews like Portable Network & COMM Kits for reliable test connectivity.
• Canary tenants: pick a small set of tenants (or an internal tenant) for initial deployment; run features with a handful of real-world tenants and iterate. See edge-assisted field kit rollouts at Edge-Assisted Live Collaboration.
• Feature flags: gate account-level sync to Google behind flags to toggle behavior per tenant.
• Dry-run mode: produce the final Google Ads API payload without executing the push; present diffs to the tenant for review. Templates and schema-driven docs can help here — see Templates-as-Code.

Migration advice: move campaign-level blocks to account-level safely

If your platform previously relied on campaign-level exclusions, migrate with these steps:

1. Inventory: export all campaign/ad-group level exclusions by tenant.
2. Normalization: canonicalize values and deduplicate by tenant and placement key.
3. Merge rules: determine precedence and whether to convert to account-level (some legacy campaign-level blocks should remain scoped).
4. Communication: notify tenants and provide an approval UI for the migration plan (show what will change).
5. Execute in batches with reconciliation and rollback capabilities.

Example flow: creating an account-level exclusion and syncing to Google Ads

Step-by-step

1. Tenant calls POST /tenants/{id}/exclusions with idempotency_key.
2. API validates and stores record as pending_sync, logs creator and timestamp.
3. Background worker picks up the job, batches with other changes for the same Google account, and calls Google Ads batch API to create/update account exclusion list.
4. On success, worker writes external_id(s), updates status to active, and emits an event to the tenant’s audit log and UI.
5. Reconciliation job verifies existence and flags drift if mismatch detected.

ASCII DIAGRAM:
Tenant UI ---> API (validates) ---> DB (pending_sync) ---> Worker Queue ---> Google Ads API
                                              ^                                       |
                                              |                                       v
                                       Reconciliation <----------------------------- Google Ads
  

Operational cost and SLA considerations

Each tenant change costs developer and API quota resources. Consider tiering service levels:

• Free tier: limited daily bulk imports and slower sync windows (e.g., 6–12 hours).
• Standard tier: near-real-time sync (minutes) with throttles.
• Enterprise tier: guaranteed priority and human review paths for emergency unblocks and global overrides.

For pricing and SLA design patterns, consult cloud cost playbooks like Cloud Cost Optimization and operational estimates in cost playbooks.

Security checklist

• Use least-privilege OAuth scopes for Google Ads service accounts.
• Rotate service account credentials and monitor their use.
• Encrypt PII and sensitive metadata in transit and at rest.
• Rate-limit and validate API consumers to limit abuse (example: bulk imports submitted with malformed lists).
• Implement anomaly detection — sudden spikes in exclusions may indicate abuse or misconfiguration.

2026 trends that affect your design

Design choices should reflect industry trends through late 2025 and early 2026:

• Platform automation acceleration: More advertisers use automated formats (Performance Max, Demand Gen). Account-level guardrails are increasingly necessary to protect brand safety while preserving automation.
• Privacy & measurement changes: With evolving privacy standards, context-based blocking and inventory signals will become more prominent; design metadata fields to store relevance signals.
• API-first integrations: Ad platforms are enhancing API features (e.g., Google Ads’ account-level exclusions) — build modular sync layers that adapt to API changes without rewriting business logic. See API-first patterns in Compose.page for Cloud Docs.
• Demand for explainability: Clients expect human-readable reasons for why a placement is blocked; include reason and evidence in the audit metadata.

Case study (hypothetical): How a retail SaaS reduced false-positive blocks

A retail ad-management SaaS integrated tenant-level exclusions into Google Ads in early 2026. Problems before integration: duplicate blocks across campaigns, frequent accidental overblocking, and long reconciliation times. They implemented the design above and achieved:

• 70% fewer duplicate entries by deduplicating during ingestion.
• Near-zero overblocking incidents by introducing dry-run and approval flows for new account-level blocks.
• Faster remediation through daily reconciliation jobs and a drift dashboard, reducing mean time to detect external edits from 48 hours to 4 hours.

Actionable checklist — implement this in the next 90 days

1. Define your data model and add precedence and external_id fields.
2. Design REST endpoints with idempotency keys and bulk import support.
3. Add validation rules and a denylist; normalize placement values on ingest.
4. Implement background workers for batched Google Ads sync and a daily reconciliation job.
5. Build RBAC with approval flows and audit logging for every change.
6. Launch to a canary tenant in dry-run mode, then roll out with feature flags.

Closing: predictable controls, safer automation

Account-level placement exclusions are a powerful tool for brand safety in 2026. For SaaS platforms, exposing that control to tenants is a competitive advantage — but only if you do it safely. Use clear precedence rules, strong permission models, strict validation, idempotent APIs, and robust sync and reconciliation with Google Ads. These practices reduce operational overhead, protect tenants, and keep automated formats running effectively.

Next steps (call-to-action)

Ready to build this into your platform? Start with the 90-day checklist above. If you want a ready-made pattern, download our open-source reference implementation (API schema, worker patterns, reconciliation scripts) or schedule a technical review with our team to adapt the blueprint to your architecture.

Related Reading

• Observability for Workflow Microservices — tracing, monitoring and reconciliation
• Templates-as-Code and API schema workflows
• Compose.page for Cloud Docs — documenting APIs and schemas
• Open Middleware Exchange — standards for API-first integrations
• Designing a Unified Loyalty Program for Independent Bike Shops
• Cashtags and Fan Investment: Could Fans Use Social Finance to Fund Local Teams and Gear Drops?
• Upcycle Ideas: Turn Old Hot-Water Bottle Covers into Cozy Homewares to Sell
• YouTube's Monetization Update: New Opportunities for Coverage of Sensitive Topics
• R&D and Data: Claiming Credits for Building an Autonomous, Data-Driven Business