PATCH/v1/items/{id}

Repair or edit an item

A NEEDS_ATTENTION item takes a new recipient and variables, is validated again and re-enters the queue (ITEM-004). A HELD item accepts a new send date, external id and metadata. Later statuses cannot be edited.

Scope items.write

Path parameters

idstringrequired

Body

recipientobject

6 fields

namestringmax length 200

addressLine1stringmax length 200

addressLine2string or null

postalCodestringmax length 20

citystringmax length 120

countrystringmax length 40

variablesobject

sendDatedate or null

externalIdstring or null

metadataobject or null

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

409The item cannot be edited in its status (invalid_item_transition)

422Validation failed

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

otherError (RFC 9457 problem details)

Request

curl -X PATCH https://api.postbuddy.nl/v1/items/itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K \
  -H "Authorization: Bearer $POSTBUDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Sanne de Vries",
      "addressLine1": "Oudegracht 112",
      "postalCode": "3511 AX",
      "city": "Utrecht",
      "country": "NL"
    },
    "variables": {
      "first_name": "Sanne"
    },
    "externalId": "crm-0062p00001Xyz"
  }'

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

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

const result = await client.items.repair('itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K', {
  body: {
    recipient: {
      name: 'Sanne de Vries',
      addressLine1: 'Oudegracht 112',
      postalCode: '3511 AX',
      city: 'Utrecht',
      country: 'NL',
    },
    variables: {
      first_name: 'Sanne',
    },
    externalId: 'crm-0062p00001Xyz',
  },
});

import os
from postbuddy import Client

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

result = client.items.repair("itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K", {
    "recipient": {
        "name": "Sanne de Vries",
        "addressLine1": "Oudegracht 112",
        "postalCode": "3511 AX",
        "city": "Utrecht",
        "country": "NL",
    },
    "variables": {
        "first_name": "Sanne",
    },
    "externalId": "crm-0062p00001Xyz",
})

Response

{
  "id": "itm_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/invalid_item_transition",
  "title": "Invalid item transition",
  "status": 409,
  "code": "invalid_item_transition",
  "detail": "The item cannot be edited in its status (invalid_item_transition)",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}

{
  "type": "https://docs.postbuddy.nl/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "Validation failed",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "errors": [
    {
      "field": "recipient.postalCode",
      "code": "invalid_string",
      "message": "Invalid postal code"
    }
  ]
}