GET/v1/postbatches/{id}/items

List the items of a Postbatch

The item list conventions (status, needsAttention, externalId, createdAt, q and the other item filters) scoped to the Postbatch; cursor paged.

Scope items.read

Path parameters

idstringrequired

Query parameters

limitintegermin 1max 200default 50

cursorstring

Opaque cursor from nextCursor of the previous page (same sort and filters).

sortstring

Comma separated, prefix - for descending; fields: createdAt, sendDate. Default -createdAt.

includeenum

include=total adds totalCount.

total

filter[status]enum

NEEDS_ATTENTIONSUPPRESSEDHELDPENDING_APPROVALREADYSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

filter[status][in]string

Comma separated values

filter[status][ne]enum

NEEDS_ATTENTIONSUPPRESSEDHELDPENDING_APPROVALREADYSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

filter[postflowId]string

filter[postflowId][in]string

Comma separated values

filter[postbatchId]string

filter[postbatchId][in]string

Comma separated values

filter[integrationInstallationId]string

filter[integrationInstallationId][in]string

Comma separated values

filter[isTest]boolean

filter[isSample]boolean

filter[externalId]string

filter[externalId][in]string

Comma separated values

filter[createdAt][gte]date-time

filter[createdAt][gt]date-time

filter[createdAt][lte]date-time

filter[createdAt][lt]date-time

filter[sendDate][gte]date-time

filter[sendDate][gt]date-time

filter[sendDate][lte]date-time

filter[sendDate][lt]date-time

filter[sendDate][null]boolean

filter[search][contains]string

Returns

4 fields of the 200 answer

dataarray of objectsrequired

29 fields

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

nextCursorstring or nullrequired

hasMorebooleanrequired

totalCountinteger

Responses

200Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

422Validation failed

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

otherError (RFC 9457 problem details)

Request

curl https://api.postbuddy.nl/v1/postbatches/pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K/items?limit=20 \
  -H "Authorization: Bearer $POSTBUDDY_API_KEY"

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

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

const result = await client.postbatches.items('pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K', {
  query: {
    limit: 20,
  },
});

import os
from postbuddy import Client

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

result = client.postbatches.items("pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K", query={
    "limit": 20,
})

Response

{
  "data": [
    {
      "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"
      }
    }
  ],
  "nextCursor": "Example",
  "hasMore": false,
  "totalCount": 3
}

{
  "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/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"
    }
  ]
}