segment_delete

publ Reference
[Migration map](../reference/tool-name-migration.md).

# segment_delete

Delete one observed non-preset segment using the source single-row action. Requires [MANAGE_SEGMENT and exact identities](publ_segments_get.md#access-and-identity), a fresh detail revision and explicit confirmation. There is no arbitrary batch API in this tool.

## Input

| Input | Contract |
| --- | --- |
| channelCode | Required selected channel code. |
| distinctId | Required observed opaque segment identity, never numeric id or title. |
| requestId | Required stable `[A-Za-z0-9_-]{8,80}` ID. |
| expectedRevision | Required selected detail revision, 64 lowercase hexadecimal characters. |
| confirmation | Required literal DELETE_SEGMENT. |
| dryRun | Optional boolean, default false. |

```json
{"channelCode":"selected-channel-code","distinctId":"observed-segment","requestId":"segment-delete-001","expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000","confirmation":"DELETE_SEGMENT","dryRun":true}
```

Replace illustrative IDs/revision with observed values. All objects are strict. Presets, stale revisions, malformed identities and changed context fail without dispatch.

## Delete and verification

Preparation reads full selected detail and two complete inventories, each bounded to 2,000 rows/20 pages at 100 rows. Totals and numeric/opaque identities must be stable and unique. Over-limit, incomplete or changing inventories cannot establish deletion. The source record must still exactly match its revision, and all context/detail/inventory guards repeat before dispatch.

A fresh dry run returns SEGMENT_PLAN, changes:{}, plannedStages delete/full-readback, writesPerformed:false and verification.confirmed:false; it saves no job. Existing request IDs follow the [apply fingerprint/dry-run rules](publ_segment_apply.md#prepare-save-and-preservation).

A durable write-sent journal precedes POST `/seller/api/v1/segment-management/segments/bulk-delete` with exactly one distinctId. HTTP 200 or 204 is acknowledged; no response body is needed. Acknowledgement alone does not complete the task. The selected detail must be absent via the adapter's known-404 handling, two complete stable inventories must equal the original inventory minus only that target, and selected absence plus context are checked again. Other remaining rows, including timestamps, must be preserved.

## Inputs

| Field | Required here | Contract |
| --- | --- | --- |
| `distinctId` | Yes | string; pattern `^[A-Za-z0-9_-]{1,128}$` |
| `confirmToken` | No | string; pattern `^ct[a-f\d]{32}$`; The confirmToken from this tool's preview result. Omit it to preview; repeat the same input with it to execute. |

## Result and recovery

Uses SEGMENT_PENDING/SEGMENT_COMPLETE, taskType:segment and prepared/write-sent/done as described in [saved work and recovery](../guides/segments.md#saved-work-and-recovery). Completion returns segment:null and revision:null. Lost/uncertain deletion is never resent: write-sent resume uses observations to verify absence and preservation. Prepared resume may still dispatch the original first deletion. Standalone description:null is accepted and preserved while establishing the selected detail revision; changing it to empty string is still business drift. No automatic recreation or rollback exists.

Status/completed replay is historical and verification.confirmed:false. Inspect lastResult, outcome, acknowledged, writesPerformed and any journalPersistence failure together. A read/permission failure is not proof of absence; incomplete cleanup is not success. Navigation is the actual segments list, where deletion is a modal. Completion does not prove that linked promotions, visitor access, member eligibility or historical references were recalculated.

Current observations use the [bounded response and recovery rules](../guides/segments.md#oversized-responses-and-recovery).
An oversized response is not a successful empty result. If a write was already
sent, retain its original task and reconcile; the failed read does not authorize
repeating the change.