Change a batch's follow-up policy

POST/v1/batches/{id}/policy_change

Changes the follow-up policy of the batch's deliveries that have not yet confirmed. With dry_run: true, shows what would change and what it would cost, and changes nothing.

Path parameters

idstringrequired

The batch's ID, starting bat_.

Body

Required

policy_idstring · nullablerequired

The new follow-up policy's ID (rpol_…), or null (or rpol_none) for none.

Optional

scopestring

For a batch only.
One of batch_followers all_pending
Default "batch_followers"
startobject

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.
2 fields of start
- start.fromstring
  
  One of first step
- start.stepinteger
  
  at least 1
extend_expiry_tostring · date-time · nullable

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_runboolean

When true, nothing changes: the response says what the change would do. Default false.
Default false

Returns

200 application/json. What changed — or, with dry_run, what would.

Errors have one shape; see Errors for every code.

Code language

Request

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

const res = await fetch('https://api.parasend.com/v1/batches/bat_01M6R27T8SXWNM911FS53W4S9F/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();

import os, requests, uuid

res = requests.post(
    "https://api.parasend.com/v1/batches/bat_01M6R27T8SXWNM911FS53W4S9F/policy_change",
    headers={
        "Authorization": f"Bearer {os.environ['PARASEND_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "policy_id": "rpol_01M6R27T5NK3830GCN9QPS9M95",
        "dry_run": True,
    },
)
data = res.json()

using var http = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.parasend.com/v1/batches/bat_01M6R27T8SXWNM911FS53W4S9F/policy_change");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("PARASEND_KEY"));
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent("""
{
  "policy_id": "rpol_01M6R27T5NK3830GCN9QPS9M95",
  "dry_run": true
}
""", Encoding.UTF8, "application/json");
var response = await http.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

var json = """
    {
      "policy_id": "rpol_01M6R27T5NK3830GCN9QPS9M95",
      "dry_run": true
    }
    """;
var request = HttpRequest.newBuilder(URI.create("https://api.parasend.com/v1/batches/bat_01M6R27T8SXWNM911FS53W4S9F/policy_change"))
    .header("Authorization", "Bearer " + System.getenv("PARASEND_KEY"))
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(json))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.parasend.com/v1/batches/bat_01M6R27T8SXWNM911FS53W4S9F/policy_change', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('PARASEND_KEY'),
        'Idempotency-Key' => bin2hex(random_bytes(16)),
    ],
    'json' => [
        'policy_id' => 'rpol_01M6R27T5NK3830GCN9QPS9M95',
        'dry_run' => true,
    ],
]);
$data = json_decode($response->getBody(), true);

Response · 200

{
  "object": "policy_change",
  "dry_run": true,
  "policy_id": "rpol_01M6R27T5NK3830GCN9QPS9M95",
  "start_step": "first",
  "affected": 2,
  "unchanged": {
    "ended": 0,
    "own_policy": 0
  },
  "not_yet_notified": 2,
  "messages": {
    "email": 0,
    "sms": 0
  },
  "first_send_at": null,
  "estimate": {
    "currency": "ISK",
    "amount": 0,
    "vat": 0,
    "total_amount": 0
  },
  "after_expiry": 0,
  "held_by_gap": 0,
  "in_flight": 0,
  "schedule": [],
  "expires_at": null,
  "expiry_capped": 0
}