# Change a delivery's follow-up policy

`POST https://api.parasend.com/v1/deliveries/{id}/policy_change`

Source: https://parasend.com/docs/api/deliveries/change-policy

Authentication: `Authorization: Bearer <API key>` (a `ps_test_` key in test mode, `ps_live_` in live mode).
Send an `Idempotency-Key` header: a retry with the same key returns the first answer.

Changes one delivery's follow-up policy. With `dry_run: true`, shows what would change and changes nothing.

## Path parameters

- `id` (string, required)

## Body (application/json)

- `policy_id` (string · nullable, required): The new follow-up policy's ID (`rpol_…`), or null (or `rpol_none`) for none.
- `scope` (string, optional): For a batch only. One of: `batch_followers`, `all_pending`. Default: `"batch_followers"`.
- `start` (object, optional): Where notified deliveries start in the new policy: `{"from": "first"}` (the default), its first reminder, or `{"from": "step", "step": n}`, step n counting from 1. The first notice is never sent again; deliveries not yet notified follow the new policy from its start.
  - `start.from` (string, optional): One of: `first`, `step`.
  - `start.step` (integer, optional)
- `extend_expiry_to` (string · date-time · nullable, optional): Move the affected deliveries' expiry to this time (ISO 8601), which must be in the future. An expiry is only ever moved later, never past a year from the delivery's creation, and never past the deletion of its documents.
- `dry_run` (boolean, optional): When true, nothing changes: the response says what the change would do. Default false. Default: `false`.

## Example: Preview a policy change

```bash
curl -X POST "https://api.parasend.com/v1/deliveries/dlv_01M6R27T05512SCV3852TPM2XY/policy_change" \
  -H "Authorization: Bearer $PARASEND_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "rpol_01M6R27T5NK3830GCN9QPS9M95",
    "dry_run": true
  }'
```

```js
const res = await fetch('https://api.parasend.com/v1/deliveries/dlv_01M6R27T05512SCV3852TPM2XY/policy_change', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PARASEND_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    policy_id: 'rpol_01M6R27T5NK3830GCN9QPS9M95',
    dry_run: true,
  }),
});
const data = await res.json();
```

## Response 200

What changed — or, with dry_run, what would.

```json
{
  "object": "policy_change",
  "dry_run": true,
  "policy_id": "rpol_01M6R27T5NK3830GCN9QPS9M95",
  "start_step": "first",
  "affected": 1,
  "unchanged": {
    "ended": 0,
    "own_policy": 0
  },
  "not_yet_notified": 0,
  "messages": {
    "email": 2,
    "sms": 0
  },
  "first_send_at": "2026-11-07T09:15:05.667Z",
  "estimate": {
    "currency": "ISK",
    "amount": 0,
    "vat": 0,
    "total_amount": 0
  },
  "after_expiry": 0,
  "held_by_gap": 1,
  "in_flight": 0,
  "schedule": [
    {
      "step": 1,
      "channel": "email",
      "day_offset": 0,
      "due_at": "2026-11-07T09:15:05.667Z"
    },
    {
      "step": 2,
      "channel": "email",
      "day_offset": 4,
      "due_at": "2026-11-11T09:15:05.667Z"
    },
    {
      "step": 3,
      "channel": "sms",
      "day_offset": 11,
      "due_at": "2026-11-18T09:15:05.667Z"
    }
  ],
  "expires_at": null,
  "expiry_capped": 0
}
```

Errors: one shape, `{"error": {type, code, message, param, request_id}}`; every code is listed at https://parasend.com/docs/errors.