docs(ads): clarify adding platforms to active syncs and segment preservation on delete

[george-dilthey]

What changed

Four targeted edits to docs/clay-ads.md:

1. "Can I add another ad platform to an existing Ad Sync?" — Replaced the incorrect "Expand your reach" claim (that section only exists in the legacy table-based ad sync experience AdAudienceSidebar, not the new Audience Ads 2.0) with the accurate answer: destination platforms are locked once a sync is active; the workaround is to delete and recreate with all destinations configured from the start. Added note that deleting the sync does not affect the underlying audience segment.

2. "Can I permanently delete an Ad Sync?" — Added a sentence clarifying that deleting an ad sync does not delete the underlying audience segment. Removed the paragraph referencing "Deactivate" as a separate UI option distinct from "Delete" — the only available action in the new Ads experience is Delete (confirmed in AdSyncsHomepageTable.tsx: sole DropdownItem labeled "Delete").

3. "Can I edit the field mapping after setting up an Ad Sync?" — Removed the reference to a "Deactivate" option (doesn't exist in the new Ads UI) and changed "deactivate or permanently delete" to just "delete". Added that deletion doesn't affect the underlying segment.

4. "Why does my ad audience show 'too small for use in campaigns'?" — Changed "deactivate the current sync" to "delete the current sync" and updated "Deactivation is permanent" to "Deletion is permanent". Added note that deleting the sync doesn't affect the underlying segment.

Why

Intercom ticket #215475650890846: Genesis-Vincent Velarde (Enterprise customer, Tealium) had 3 existing ad syncs going to LinkedIn and wanted to add Google Ads as a destination. The docs said "Expand your reach" would appear — but that section is only in the deprecated legacy table-based ad sync sidebar (AdAudienceSidebar/components/AddProviderSection.tsx), not in the new Audience Ads 2.0 experience (AdSyncs/). The customer was also unable to find a "deactivate" button (the doc described "Deactivate" as a separate option from "Delete"), and worried that clicking "Delete" would remove their audience segment (the doc said nothing about segment preservation). Support rep Ariana explicitly committed to updating the docs in the conversation.

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475650890846
• #proj-ads Slack thread (Abdul + Ariana, Aug 26): https://clay-hq.slack.com/archives/C08RWUQPPLN/p1787776073158989 — Abdul (engineer) confirmed: the only way to "deactivate" is to delete; deleting doesn't touch the underlying segment; deleting a segment does delete an ad sync.
• Code (Claim 1 — can't add destinations to active sync): apps/api/v3/ad-audiences/domain/utils.ts:274-279 — validateAdSyncEditable throws for any non-draft sync. PASS.
• Code (Claim 2 — Delete via ⋮ menu): apps/frontend/src/components/WorkspaceHomepage/AdAudiencesHomepage/AdSyncsHomepage/AdSyncsHomepageTable.tsx:55-68 — sole DropdownItem is "Delete". PASS.
• Code (Claim 3 — Delete doesn't touch segment): apps/api/v3/ad-audiences/services/ad-sync.service.ts:311-326 — tearDownAdSync soft-deletes the sync record only; no segment deletion in the call chain. PASS.
• Code ("Expand your reach" is legacy-only): apps/frontend/src/components/AdAudienceSidebar/components/AddProviderSection.tsx:115 — only in AdAudienceSidebar (deprecated table ads, confirmed by deprecation banner in AdAudienceHeader.tsx). AdSyncs/ has no equivalent component.

Uncertainties

None. All claims verified against code via the Docsbot Verifier sub-agent and corroborated by the product engineer in the #proj-ads Slack thread.

Related observations

• Existing open PRs on this doc: PRs docs(clay-ads): add audience size glossary entry and match rate vs audience size FAQ #2287, docs(clay-ads): add Audience size glossary entry, update Match rate definition, add match rate vs audience size FAQ #2286, docs(clay-ads): explain Ad sync vs Legacy ad sync difference #2256, docs(clay-ads): add EEA consent, platform fields, delete-recreate behavior, match rate clarification #2251, and docs(clay-ads): clarify Enterprise has unlimited active recurring ad syncs #2218 are all open on docs/clay-ads.md. None touch the four sections I'm modifying. PR docs(clay-ads): add EEA consent, platform fields, delete-recreate behavior, match rate clarification #2251 adds content about what happens to the ad platform's audience list when you delete and recreate (a different topic than Clay segment preservation), so reviewers should verify the two don't create a contradiction when both merge.
• Abdul mentioned "i am adding this feature to pause and edit this week" — a pause/edit capability that would let customers add destinations to active syncs without deleting. Not documented here (not yet shipped), but worth watching for a follow-up doc update.
• The FAQ title "Will I be charged again if I deactivate and recreate an Ad Sync?" still uses "deactivate" — left unchanged to avoid breaking the anchor link #will-i-be-charged-again-if-i-deactivate-and-recreate-an-ad-sync which is referenced from multiple places in the doc.
• Linear issue FED-3221 ("unable to add destinations to an existing ad sync") was linked to this Intercom conversation — indicates the product team is tracking this limitation.

Closes DOC-2105

[linear-code]

DOC-2105