POST/v1/templates/{id}/versions/{number}/samples

Order a physical sample of a version

A paid single item (isSample) with the given recipient and sample data, priced as one piece and released to the next production run at once. Needs postbatches.write or postflows.write and the samples feature of the plan.

Scope templates.readRate limit class itemCreate

Path parameters

numberstringrequired

idstringrequired

Body

recipientobjectrequired

6 fields

namestringmax length 200

addressLine1stringmax length 200

addressLine2stringmax length 200

postalCodestringmax length 20

citystringmax length 120

countrystringmax length 40

variablesobjectdefault {}

finishstringmin length 1max length 40

Returns

29 fields of the 202 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

202Success

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 -X POST https://api.postbuddy.nl/v1/templates/tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K/versions/tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K/samples \
  -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"
    }
  }'

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

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

const result = await client.samples.order('tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K', 'tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K', {
  body: {
    recipient: {
      name: 'Sanne de Vries',
      addressLine1: 'Oudegracht 112',
      postalCode: '3511 AX',
      city: 'Utrecht',
      country: 'NL',
    },
    variables: {
      first_name: 'Sanne',
    },
  },
});

import os
from postbuddy import Client

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

result = client.samples.order("tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K", {
    "recipient": {
        "name": "Sanne de Vries",
        "addressLine1": "Oudegracht 112",
        "postalCode": "3511 AX",
        "city": "Utrecht",
        "country": "NL",
    },
    "variables": {
        "first_name": "Sanne",
    },
})

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