Migration map.

marketing_banner_apply

See the current correction and older-server guidance before preparing new inputs; keep existing task inputs unchanged during recovery.

Create a default banner, change visibility, or compose content/image/visibility changes through one tool. The selected object is globalBanner; the other widget and all unrelated custom settings must be preserved.

Access and preparation

Requires OWNER or DELEGATEE with MANAGE_MARKETING_TOOLS for the selected channel. An unrelated permission or CREATOR role is insufficient. The source-defined hosted selected-channel resource admits this tool only for its exact channelCode; the account resource excludes it.

Read marketing_banner_get first and retain its exact revision. New plans independently reread the full custom record and plan, then verify channel/context continuity. The revision includes unrelated settings, timestamps and plan; a change returns MARKETING_CONFLICT before dispatch. Later plan changes return MARKETING_PLAN_CHANGED and pause remaining effects.

The host configures CHANNEL_ENV. Replacement images additionally require a resource gateway, upload bucket and region, including for dry runs. No DNS/recache service is used. A no-op skips mutation-service validation but still performs preparation reads. Service URLs and credentials are not inputs.

Inputs and actions

The outer object, settings, images and each image object are strict. Action-specific combinations are runtime refinements beyond the exported flat object schema.

create accepts no visible/settings/images. It writes source defaults only when this widget is absent; an existing widget is a no-op. Defaults start NOT_ACTIVATED. visibility requires an existing widget and visible; settings/images are forbidden. It changes only is_activated while retaining the complete existing content.

configure merges supplied settings/images and optional visible into one final nested save. It requires at least one supplied setting, image slot or visible, checked by the workflow after schema parsing. Missing widgets start from source defaults. Even a configure containing only visible or unchanged values requires a recognized eligible editor plan. Use visibility for the separate visibility action. Denied or unknown plans return action_required / MARKETING_EDIT_PLAN_REQUIRED with the exact screen's human-console guidance and no writes. No plan upgrade or payment occurs. See the complete eligibility list.

Settings

Creation defaults are title TITLE, description DESCRIPTION, title_color and description_color #FFFFFF, bg_color #000000, empty desktop/mobile images, https://publ.co with WEB_LINK, and GLOBAL_BANNER_TYPE_B. They are creation values, never fallbacks for malformed reads. There is no per-slot visibility or widget deletion action.

Text is not trimmed; empty is allowed where listed, and a single character is rejected. Supplied links are limited to 4,096 characters before removing all whitespace and adding https:// when no HTTP(S) prefix exists. Nonempty results require HTTP(S), a hostname, no embedded credentials and the source domain-pattern match. This is validation/normalization, not URL fetching or destination availability verification. WEB_LINK and INTERNAL_LINK retain the source's new-tab/current-tab choice; INTERNAL_LINK does not accept a separate page-ID field.

Images

All replacement files together may contain at most 5 MiB of original bytes. This aggregate cap is a bridge policy for its 8 MiB request envelope, not a source-widget file-size rule. Extension matching is case-insensitive at runtime but the exported regex omits the flag; use lowercase filenames for both. Parsed bytes must match PNG/JPEG structure and extension. The bridge does not resize or render them. null stores an empty image reference and sends no upload; arbitrary replacement image URLs are not accepted.

Do not retry a pending image with a new request ID.

Input examples

These illustrate dry-run inputs, not observed service results. Replace the channel/revision and choose the user's intended content.

{
  "channelCode": "selected-channel-code",
  "requestId": "banner-create-plan-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "action": "create",
  "dryRun": true
}

{
  "channelCode": "selected-channel-code",
  "requestId": "banner-visibility-plan-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "action": "visibility",
  "dryRun": true,
  "visible": false
}

{
  "channelCode": "selected-channel-code",
  "requestId": "banner-configure-plan-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "action": "configure",
  "dryRun": true,
  "settings": {
    "title": "Welcome",
    "description": "Latest news"
  }
}

{
  "channelCode": "selected-channel-code",
  "requestId": "banner-image-plan-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "action": "configure",
  "dryRun": true,
  "images": {
    "desktop_bg_image_src": {
      "filename": "banner.png",
      "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aDWQAAAAASUVORK5CYII="
    }
  }
}

Effects and results

A new dry run returns MARKETING_WIDGET_PLAN, noop, normalized changes and plannedStages, with no task creation or business writes. Image bytes are replaced with metadata in the planned changes. With an existing matching task, dryRun returns historical saved progress as a plan rather than a fresh business preview.

A real no-op writes a completed journal without business requests. For a change, the workflow can initialize a missing custom record with a bodyless HTTP200 POST to /seller/api/v1/channel-management/custom, retain its observed full baseline, issue/upload each replacement image, then PUT /seller/api/v1/channel-management/custom/experimentals with one nested globalBanner object. That object merges requested values with preserved fields; it is not a replacement of the whole experimentals object. The save expects HTTP200 without a response-body contract. There is no recache step.

The final readback must preserve every unrelated business setting, the other widget, unknown nested JSON, record ID, channel ID and insertedAt. updatedAt may change during the save. Only top-level experimentals.id/exp_id are excluded. The workflow checkpoints before each effect, but does not use a server-side compare-and-swap or transaction. Failed uploads/saves can leave initialized records or orphaned objects; no rollback or automatic deletion occurs.

MARKETING_WIDGET_COMPLETE includes widget, revision, phase done, historical, initializationAcknowledged, settingsSaveAcknowledged and uploads. Fresh completion confirms stored readback only. A no-op has no save acknowledgement; readback-only reconciliation can also complete without a save acknowledgement or proven causality. writesPerformed is false for a no-op or untouched prepared phase, true when an initialization/save or uploaded-object receipt exists, and otherwise null.

MARKETING_WIDGET_PENDING retains phase, uploads, lastResult and inspect_task guidance. journalPersistence.saved:false means the error checkpoint was not saved. Authentication/context errors can suppress channel/navigation metadata. Image receipts contain generated storage coordinates and checksums, not raw bytes or temporary credentials.

Task recovery

Use taskType marketing-widget and the original taskId with status or resume. The task binds widget kind, channel/context, original revision/plan, normalized input fingerprint, record snapshots and image metadata. The same requestId cannot switch between banner and popup or change the input. Unknown or inconsistent journals fail validation; do not edit or rename them to bypass it.

Status never advances effects. Resume may run untouched stages; no sent boundary is automatically reset, even after definite failure. A rejected continuation of a completed task returns its error without writing an error detail into the completed journal.

The marketing-widget namespace uses the selected task store. For a deliberate later restoration, obtain a fresh reader revision and separately authorized input; retain uncertain tasks.

Saved record identity

A missing record differs from an existing malformed record. Stored JSON null, false, zero or an empty string is rejected with TASK_STATE_UNVERIFIED by the existing record validator. Apply/dry-run/status/resume must not overwrite it or treat it as a fresh task. Preserve the file for inspection; do not delete/edit it or replace the request ID to bypass the error. Existing valid task recovery and genuinely missing-record behavior remain unchanged.