POST/v1/items/{id}/cancel

Cancel an item

Allowed until the run cutoff (HELD, PENDING_APPROVAL, READY, NEEDS_ATTENTION); a reservation is released (ITEM-005).

Scope items.writeIdempotent with a key

Path parameters

idstringrequired

Headers

Idempotency-Keystringmax length 255

Up to 255 characters, scoped to the organisation and the endpoint, kept for 24 hours: a repeat with the same body replays the stored response with Idempotent-Replayed: true (API-004).

Returns

29 fields of the 200 answer

idstringrequired

statusenumrequired

NEEDS_ATTENTIONSUPPRESSEDHELDPENDING_APPROVALREADYSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

customerStatusenumrequired

NEEDS_ATTENTIONSUPPRESSEDSCHEDULEDIN_PRODUCTIONHANDED_TO_CARRIERCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

needsAttentionbooleanrequired

warningsarray of objectsrequired

3 fields

codeenumrequired

address_invalidpostal_code_invalidhouse_number_missingcity_missingcountry_not_supporteddestination_not_supportedvariable_missingvariable_type_invalidvariable_too_longimage_fetch_failedimage_resolution_lowtext_overflowexpression_invalidlate_delivery_expectedwaiting_for_fundssuppressedcarrier_codes_missingexcluded_from_run

fieldstringrequired

messagestringrequired

sourceenumrequired

POSTFLOWPOSTBATCHSAMPLE

postflowIdstring or nullrequired

postbatchIdstring or nullrequired

templateVersionIdstring or nullrequired

productobjectrequired

4 fields

idstringrequired

specificationIdstringrequired

finishstringrequired

destinationstringrequired

advertisingCategorystring or nullrequired

isTestbooleanrequired

isSamplebooleanrequired

recipientobject or nullrequired

6 fields

namestringrequired

addressLine1stringrequired

addressLine2string or nullrequired

postalCodestringrequired

citystringrequired

countrystringrequired

variablesobject or nullrequired

sendDatedate or nullrequired

externalIdstring or nullrequired

metadataobject or nullrequired

createdAtdate-timerequired

updatedAtdate-timerequired

readyAtdate-time or nullrequired

scheduledAtdate-time or nullrequired

handedToCarrierAtdate-time or nullrequired

completedAtdate-time or nullrequired

failedAtdate-time or nullrequired

cancelledAtdate-time or nullrequired

anonymisedAtdate-time or nullrequired

qrobject or nullrequired

4 fields

shortUrlstringrequired

scanCountintegerrequired

firstScannedAtdate-time or nullrequired

lastScannedAtdate-time or nullrequired

priceobject or nullrequired

11 fields

idstringrequired

unitPriceCentsintegerrequired

listUnitPriceCentsintegerrequired

currencystringrequired

discountPercentnumber or nullrequired

tierQuantityintegerrequired

tierBasisenumrequired

postbatchrolling30d

basisQuantityintegerrequired

vatTreatmentstringrequired

vatRateintegerrequired

computedAtdate-timerequired

Responses

200Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

409A request with this Idempotency-Key is still in progress (idempotency_in_progress)

422Validation failed, or the Idempotency-Key was used with another body (idempotency_key_reused)

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

Request

curl -X POST https://api.postbuddy.nl/v1/items/itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K/cancel \
  -H "Authorization: Bearer $POSTBUDDY_API_KEY" \
  -H "Idempotency-Key: crm-0062p00001Xyz-signed"

import { PostBuddyClient } from '@postbuddy/sdk';

const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! });

const result = await client.items.cancel('itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K', { idempotencyKey: 'crm-0062p00001Xyz-signed' });

import os
from postbuddy import Client

client = Client(os.environ["POSTBUDDY_API_KEY"])

result = client.items.cancel("itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K", idempotency_key="crm-0062p00001Xyz-signed")

Response

{
  "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "status": "HELD",
  "customerStatus": "SCHEDULED",
  "needsAttention": false,
  "warnings": [],
  "source": "POSTFLOW",
  "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "postbatchId": "pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "templateVersionId": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "product": {
    "id": "prd_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "specificationId": "psp_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "finish": "silk",
    "destination": "Example"
  },
  "advertisingCategory": "Example",
  "isTest": false,
  "isSample": false,
  "recipient": {
    "name": "Sanne de Vries",
    "addressLine1": "Oudegracht 112",
    "addressLine2": "2nd floor",
    "postalCode": "3511 AX",
    "city": "Utrecht",
    "country": "NL"
  },
  "variables": {
    "first_name": "Sanne"
  },
  "sendDate": "2026-11-02",
  "externalId": "crm-0062p00001Xyz",
  "metadata": {
    "crmRecordId": "0062p00001Xyz"
  },
  "createdAt": "2026-10-16T09:14:02.000Z",
  "updatedAt": "2026-10-16T09:14:02.000Z",
  "readyAt": "2026-10-16T09:14:02.000Z",
  "scheduledAt": "2026-10-16T09:14:02.000Z",
  "handedToCarrierAt": "2026-10-16T09:14:02.000Z",
  "completedAt": "2026-10-16T09:14:02.000Z",
  "failedAt": "2026-10-16T09:14:02.000Z",
  "cancelledAt": "2026-10-16T09:14:02.000Z",
  "anonymisedAt": "2026-10-16T09:14:02.000Z",
  "qr": {
    "shortUrl": "https://example.com/r/Fq3ZtR8w",
    "scanCount": 3,
    "firstScannedAt": "2026-10-16T09:14:02.000Z",
    "lastScannedAt": "2026-10-16T09:14:02.000Z"
  },
  "price": {
    "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "unitPriceCents": 1250,
    "listUnitPriceCents": 1250,
    "currency": "EUR",
    "discountPercent": 3,
    "tierQuantity": 1,
    "tierBasis": "postbatch",
    "basisQuantity": 1,
    "vatTreatment": "Example",
    "vatRate": 1,
    "computedAt": "2026-10-16T09:14:02.000Z"
  }
}

{
  "type": "https://docs.postbuddy.nl/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Not found",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}

{
  "type": "https://docs.postbuddy.nl/errors/idempotency_in_progress",
  "title": "Request with this idempotency key in progress",
  "status": 409,
  "code": "idempotency_in_progress",
  "detail": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}

{
  "type": "https://docs.postbuddy.nl/errors/idempotency_key_reused",
  "title": "Idempotency key reused with a different body",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "Validation failed, or the Idempotency-Key was used with another body (idempotency_key_reused)",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "errors": [
    {
      "field": "recipient.postalCode",
      "code": "invalid_string",
      "message": "Invalid postal code"
    }
  ]
}