Conversion links

OWNER or DELEGATEE needs MANAGE_CONVERSION_LINKS for the exact selected channel. Marketing-tools permission alone does not suffice. Source account resources exclude the three tools and conversion-link recovery; no domain prerequisite is added. Creation requires a verified eligible source plan; existing-link reads/editing/cleanup are not gated by creation eligibility. See the exact policy. Missing/unknown plans fail closed and the person receives the human plan destination, without a purchase or billing call.

Read and plan

Read a bounded list and use its creationRevision only for create. For update/visibility/delete, read each selected numeric id in detail and use its revision; a list row or keyword is not a revision.

{
  "channelCode": "selected-channel-code",
  "view": {
    "kind": "list",
    "page": 1,
    "limit": 15
  }
}

The create workflow combines source wizard fields. This sample is a dry run; replace its zero digest with the returned creationRevision. dryRun defaults to false when omitted.

{
  "channelCode": "selected-channel-code",
  "requestId": "conversion-guide-01",
  "action": "create",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "name": "Welcome link",
    "title": "Welcome to our channel",
    "description": "Read our latest updates.",
    "destination": {
      "kind": "WEB",
      "url": "https://example.com/welcome"
    }
  },
  "dryRun": true
}

After inspecting the plan, apply the intended operation and retain the requestId and original input. UTM defaults to direct / (none) with empty campaign/content/term. A keyword is server-generated. Creation normalizes only canonical numeric receipt id/channelId while preserving a nonempty opaque auto-created segment identity. Old unknown-ID tasks are not repaired or adopted by this correction. Creation may additionally create a segment; returned segment metadata does not verify its contents or authorize automatic campaign creation. Destination/UTM/keyword cannot be edited afterward through this workflow. Update supports name, sharing title/description and original thumbnail only.

Original PNG/JPEG thumbnails must be below 10,000,000 decimal bytes. Omission preserves an existing image; null removal and replacement URLs are unsupported. Upload needs configured resource gateway/bucket/region. Only verified original-byte receipts enter the save; separate upload/save effects have no rollback or object cleanup.

Continue a task

Use taskType conversion-link with the returned taskId:

{
  "taskId": "conversion-guide-01",
  "taskType": "conversion-link"
}

Status reads history. Resume may continue untouched stages after context/content checks. Sent create/update/activation/delete/grant/upload requests never repeat. Known-ID writes can reconcile by readback; a create missing its durable returned ID cannot be adopted by name. Uncertain image stages require inspection, while an unstarted upload requires the original apply bytes after restart. See the phase contract.

For visibility, unchanged targets are omitted from the effect but included in verification. One or many changed IDs use bulk activation with200/204 acknowledgement; deletion always uses bulk-delete with200/204 acknowledgement. Cross-save matching tolerates generated updatedAt only; revisions and pre-write conflict checks retain it. Deletion requires DELETE_CONVERSION_LINKS and should first be planned; success needs recognized404 detail checks plus a stable full inventory scan bounded to 5,000 links.

Share URL configuration

The host supplies conversionLinkBaseUrl in runtime service configuration or PUBL_CONVERSION_LINK_BASE_URL. Use the actual environment's HTTPS base ending in /, without credentials, query or fragment. It is separate from API and console origins and is not silently inherited across a custom API override. The returned keyword is validated and encoded as one path component. With no configured base, shareUrl is null; console navigation still works. Never guess a production hostname from an ID or another origin.

A generated share URL proves neither redirect behavior nor attribution. Destination/share/image URLs are never fetched by these tools. Detail/editor navigation uses the selected channel/id; connected tabs use their own console child paths. Demo produces no live share/navigation link.

Connected views and limits

segments reads one source-filtered page for the chosen link, defaulting to100 rows rather than the ordinary list default15. Both accept explicit15/30/50/100. It performs no condition-tree editing or member export. promotions exposes a restricted connected-benefit/campaign projection. Its source request is unpaged even though the UI has controls, so the bridge exposes source pagination and moreReported with nextPage:null rather than inventing a complete export. No financial mutation is part of these tools.

Fresh readback confirms stored fields within its stated scope; completed task history is confirmed:false.

Current read results include their selected view and retain list/segment page, size and supported filters in the single console link. Open that returned address for the same selection. CONVERSION_PAGE_OUT_OF_RANGE means the selected page is past the observed total; explicitly request page1 again. It is not a successful empty inventory, and the bridge does not choose a replacement page. The source-unpaged promotion tab remains unchanged.