Channel & Advertising Engine

Status: Draft for review

Purpose

Own adapters and synchronized state for external acquisition/distribution channels, including social advertising accounts, campaigns, creatives, catalogs/feeds and provider insights.

Owns

• External channel connections/accounts
• Provider authorization status and scoped credential references
• Provider campaign/ad-set/ad/creative mappings
• Product/catalog feed mappings and synchronization
• Provider-native delivery/sync state
• Channel insight ingestion
• Retry/reconciliation for provider API operations

Non-goals

It does not define tenant marketing strategy, own platform attribution truth, hold tenant ad-spend funds in the baseline, or expose provider credentials to browsers.

API contract — functional surface

These are contract-level resources and operations, not final controller/file names.

Method	Route	Primary actor	Contract intent
POST	/api/tenant/v1/channels/connections	Marketing Manager	Begin supported provider connection flow.
GET	/api/tenant/v1/channels/connections	Marketing Manager	List connection/account status.
POST	/api/tenant/v1/channels/{provider}/catalogs	Marketing Manager	Create/sync catalog mapping.
POST	/api/tenant/v1/channels/{provider}/campaigns/publish	Marketing Manager	Publish mapped platform campaign to provider.
PATCH	/api/tenant/v1/channels/{provider}/campaigns/{id}	Marketing Manager	Apply supported provider campaign changes.
POST	/api/tenant/v1/channels/{provider}/campaigns/{id}/pause	Marketing Manager	Pause external campaign.
GET	/api/tenant/v1/channels/{provider}/insights	Marketing Manager	Retrieve normalized provider insights.
POST	/webhooks/channels/{provider}	External Provider	Receive signed provider callbacks where supported.

All mutating operations apply the global tenant, authorization, audit and idempotency rules where relevant.

Events

• channel.connected
• catalog.synced
• ad_campaign.published
• ad_campaign.sync_failed
• channel_insights.ingested
• channel.disconnected

Roles & responsibility matrix

Legend: A accountable, R responsible, C consulted, I informed, — none.

Capability	Platform Admin	Tenant Owner	Tenant Admin	Specialist/Manager	Customer/Visitor
Provider adapter governance	A/R	I	I	C	—
Connect tenant ad account	I	A	C	R	—
Publish/pause ads	I	A	C	R	—
Catalog sync	I	A	C	R	I
Provider incident/reconciliation	R	I	C	C	—

Dependencies

• Marketing Engine for platform campaign/audience intent
• Capability/Commerce Engines for catalog/offering data
• CRM for consent-aware audience references
• Operations for workers/retry/reconciliation
• Platform Engine for plan entitlements

Internationalization Contract

• Channel adapters map canonical offerings plus locale-specific titles/descriptions/creative into provider contracts.
• Catalog/feed generation supports multiple locales without product-type-per-language service duplication.
• Provider/channel language limitations are surfaced as adapter capabilities/errors.

Security / isolation requirements

• Ad credentials are encrypted/referenced server-side only.
• Budget/state mutations require strong authorization and audit.
• Provider webhook signatures are verified.
• Tenant ad accounts remain segregated.

Acceptance criteria

• Existing Meta property/vehicle feeds can be represented through generic catalog mapping.
• Meta is an adapter, not the internal campaign domain model.
• Plan limits can restrict channels/active campaigns/features.
• Tenant ad spend is provider-billed in the baseline unless a later financial model is explicitly approved.