Migration map.

design_custom_code_apply — save advanced code

Save the requested CSS, head/body JavaScript and head HTML together as one workflow. First read design_custom_code_get and use its channel and revision. Each supplied code field replaces that entire area; it is not an append or text patch.

Input

Supply at least one code field. The object is strict: extra fields and null are invalid. All four code fields preserve omitted values and clear on an explicit empty string. Source is not trimmed, syntax-checked or normalized by this schema; whitespace is retained. No code-length maximum is declared.

{
  "requestId":"example-custom-code-001",
  "channelCode":"selected-channel-code",
  "expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
  "css":".site-title { letter-spacing: 0.02em; }",
  "headJavaScript":"window.siteLabel = `Example ${document.title}`;",
  "bodyJavaScript":"",
  "headHtml":"<meta name=\"application-name\" content=\"Example\">",
  "dryRun":true
}

Replace the placeholder channel/revision and use the intended complete source. This illustrative example clears body JavaScript and replaces the other three areas. It is not a live transcript. Inspect the plan, then retain the ID and all business inputs and change only dryRun to false to execute.

Access and storage rules

The get tool's connection, target, role and origin guards apply. Any supplied JavaScript or HTML field invokes the scripts/HTML gate, including an empty string or a value identical to existing code. An unavailable gate rejects a mixed CSS/script request with CUSTOM_CODE_UNAVAILABLE before its first write. For an independent CSS edit, omit all three JavaScript/HTML fields.

Before initialization and each remaining write, the workflow rereads channel context and availability and checks the entire original input again. A gate change after the CSS step can stop the later script/HTML step, leaving CSS saved. A skipped step already matching its expected state needs no new write; completed replays do not freshly check availability.

The bridge stores JavaScript by prefixing each backtick and dollar sign with a backslash and reverses that storage escaping on get. Pass raw JavaScript using ordinary JSON escaping only. CSS and HTML are stored without this transformation.

The read field is customCSS; its CSS write patch is customCss. Script/HTML patches use customJs, customJsBody, and customHeadTags. These are internal API field names, not additional tool inputs.

Plan and execution

For a new request, the tool compares the current full-code revision with expectedRevision and checks availability. Real execution saves a job, initializes missing shared settings with POST /seller/api/v1/channel-management/custom and {}, then applies a necessary CSS patch before one combined JavaScript/HTML patch. Initialization supplies the settings used to derive the real patches; this workflow does not explicitly change theme tone or palette.

Updates use PUT /seller/api/v1/channel-management/custom/experimentals at CHANNEL_ENV with the selected-channel bearer and channel-ID header. The workflow reads after each write and checks all four expected code fields again at completion. It performs no separate publication or credential refresh. Saved code can affect the channel immediately; the bridge does not execute it or verify its rendered behavior.

These sequential steps are not atomic. Revision comparisons cannot prevent every external change between a read and a write. Earlier successful changes can remain after a later failure; no automatic rollback is provided.

changed means the saved plan has at least one code step, not necessarily a write sent by this call. changed:false can still follow initialization. Matching readback establishes observed stored state, not which actor changed it or whether it works in a browser. A completed replay returns its historical saved result, after checking current channel context. Use get for current code.

Non-demo get/completion results can link to the advanced CSS console. In this revision, a new dry-run result lacks the task type used by that route selector and can receive the account directory link; an existing-job dry run lacks channel metadata and receives no such link. Do not infer a successful editor visit from any returned URL.

Recovery and failures

Preserve the exact parsed business inputs, request ID, connection, channel and job storage. Fingerprinting ignores the dry-run flag, but includes the exact source strings and original revision. Use task_status and task_resume with the original task ID and taskType:custom-code. A new dry run has no saved task.

Definite rejected/not-sent update failures restore that step to prepared; uncertain failures retain sending. Status returns job phase, step kinds/states and the last result. pending is saved progress, not a running background worker. Internal failures can include phase and completedSteps; the count covers completed code groups, not initialization. Outer failures can omit those fields.

Other authentication, target, origin and read failures follow the get tool's rules. An error outcome describes the failed request and does not imply earlier steps made no changes. Do not create a new request ID to force an uncertain change to repeat. Apply and shared resume are mutation-capable and carry destructive hints because existing code can be replaced or cleared.

Saved plan replay

For an existing matching task, dryRun returns historical saved plan/progress, with historical:true, replayed:true and false current verification. It performs no fresh business-state or eligibility check, no business effect and no journal change. Current console/action links are omitted. Follow nextStep for the same target's current state; keep the original task ID for uncertain-outcome recovery. Context and saved-input checks still apply. A new task follows normal fresh-plan validation; another request ID must not bypass an uncertain effect.

nextStep uses design_custom_code_get with the original channelCode; existingPhase and per-step code/state remain saved data. Reading history does not execute stored code.

Saved record identity

For this workflow, existing apply/dry-run calls and task status/resume require both the saved task ID and saved input requestId to match the requested ID. A mismatching or malformed saved identity returns TASK_STATE_UNVERIFIED before workflow context or business-state reads. Preserve the original record for inspection; do not rename/edit it, try its embedded ID or create a replacement request to bypass the error. No stored record is repaired or resent. Valid matching records retain the recovery behavior described above.

Inputs