# Delete share (`delete_share`)

Removes a share link a shopper made for a design, as Remove does on the merchant admin Shares page. The link stops opening the design for anyone who has it, and it cannot be restored. It changes no product, order or quote. The call needs confirm: true. An exact retry with the same idempotency_key replays the deletion while the share remains deleted. The result is the share as it was. It requires the shares:write scope and an idempotency_key.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/delete_share/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/delete_share.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `shares:write`
- Behaviour: destructive write

## Purpose

Stop a share link from opening the design it was made for.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | false |
| destructiveHint | true |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

- A share id from list_shares.
- A merchant has connected this store and approved the shares:write scope.

## Side effects

- Deletes the share link permanently. Anyone who has the link can no longer open the design.
- Changes no product, order or quote.
- Claims the idempotency_key for at least 24 hours.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `share_id` | integer | yes | The share id, from list_shares. |
| `confirm` | boolean | yes | Must be true to apply the change, because the share link stops opening the design permanently and cannot be restored. Without it the call returns a confirmation_required error and changes nothing. |
| `idempotency_key` | string | yes | A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict. |

## Result

The share as it was, so a caller can report what it removed.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `share_id` | integer | yes |  |
| `deleted` | boolean | no | Present and true when the share was removed. |
| `share` | object | no | The share as it was, so a caller can report what it removed. |
| `share.id` | integer | yes |  |
| `share.customiser_id` | integer | yes |  |
| `share.customiser_name` | string | yes |  |
| `share.image_url` | string or null | no | The product image of the customiser, as the merchant admin shows it. Null when the customiser has none. |
| `share.created_at` | string or null | no | When the shopper made the link, UTC. Null on links older than the record. |
| `idempotent_replay` | boolean | no | True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again. |

## Error cases

| Code | Recovery |
| --- | --- |
| `confirmation_required` | Send confirm: true. A deleted share link cannot be restored. |
| `idempotency_subject_changed` | The share changed after the recorded deletion. Issue a new key and re-check the share before writing again. |
| `insufficient_scope` | The connection was approved without shares:write. |
| `resource_not_found` | No share with that id belongs to this store, or it was already deleted. |

## Example: Remove a share link

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_share",
    "arguments": {
      "share_id": 512,
      "confirm": true,
      "idempotency_key": "6e0c2f5a-91b4-4d7e-8a3c-5f1d2b9e0a64"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "share_id": 512,
      "deleted": true,
      "share": {
        "id": 512,
        "customiser_id": 42,
        "customiser_name": "Neon signs",
        "image_url": "https://cdn.example.com/customisers/42/product.png",
        "created_at": "2026-07-18T03:14:15Z"
      },
      "idempotent_replay": false
    }
  }
}
```

## Example: Without confirmation nothing is deleted (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_share",
    "arguments": {
      "share_id": 512,
      "confirm": false,
      "idempotency_key": "6e0c2f5a-91b4-4d7e-8a3c-5f1d2b9e0a64"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Deleting share 512 stops its link opening the design permanently.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}
```
