Poste Returns

A return (restituzione, Poste Reverse) is a Poste waybill that brings the parcel from the recipient back to your return address, through an acceptance channel. It exists in two forms:

Issued with the shipment — Poste Andata & Ritorno: the return label is created together with the outbound one.
Booked on demand on an existing domestic Poste shipment, through POST /shipments/{ldv}/return.

In both cases the shipment carries the return LDV in returnTrackingNumber, and the tracking.update webhook carries it as return_ldv.

Return label issued with the shipment

Available on Poste Business Express contracts (accessory service Andata & Ritorno, APT000929), Italy only. The shipment is created with returnTrackingNumber.

By default the return label follows the outbound label in the same file (label.pdf / label.zpl). With "options": { "returnLabel": "separate" } it comes apart:


{
  "trackingNumber": "DEMO05407027",
  "returnTrackingNumber": "DEMO05407028",
  "...": "...",
  "label": { "format": "PDF", "pdf": "<base64>", "zpl": null },
  "returnLabel": { "trackingNumber": "DEMO05407028", "pdf": "<base64>", "zpl": null, "code": null }
}

Field	Type	Description
`returnLabel`	`object\|null`	Only with `returnLabel=separate`; `null` when the shipment has no return label
`returnLabel.trackingNumber`	`string`	LDV of the return (`returnTrackingNumber`)
`returnLabel.pdf`, `returnLabel.zpl`	`string\|null`	Base64, in the format Poste issued it
`returnLabel.code`	`string\|null`	Base64 GIF of the 2D code of a paperless return; `pdf` and `zpl` are then `null`

The same returnLabel=merged|separate parameter works on GET /shipments/{ldv}/label. If Poste confirms the outbound shipment but not the return, the shipment is created with hasWarning: true.

Book a return

POST /shipments/{ldv}/return — rate limit 30 / min · requires an active subscription

Books a Poste return on a domestic Poste shipment (Business Express or Standard) that has no return yet. Poste charges it only at the first scan, and so does the platform: a booked return that is never used costs nothing.

Field	Type	Required	Description
`channel`	`string`	Yes	Acceptance channel, see below
`paperless`	`boolean`	No	No label: the recipient shows a 2D code (`returnLabel.code`). Only with Punto Poste and post office

`channel`	Where the parcel is handed over	Limits
`APT000928`	Home pickup
`APT000979`	Punto Poste shop	max 36 × 37 × 56 cm, 15 kg
`APT000980`	Punto Poste Locker	max 36 × 37 × 56 cm, 15 kg
`APT000981`	Post office	sum of the sides under 150 cm, each side under 100 cm, under 30 kg

Request


{ "channel": "APT000979", "paperless": true }

HTTP	`code`	When
`402`	`subscription_required` · `subscription_payment_failed` · `plan_limit_reached`	Subscription missing, unpaid or limit reached
`404`	`not_found`	Unknown LDV
`409`	`invalid_state`	Not a domestic Poste shipment, or it already has a return
`422`	`validation_failed`	Unknown `channel`; return address of the pickup point incomplete or outside Italy; parcel beyond the limits of the channel
`422`	`carrier_error`	The channel is not configured on the platform
`502`	`carrier_error`	Poste refused the booking; the reason is in `message`

Read a return

GET /shipments/{ldv}/return?files=1

The return of the shipment, whichever way it was created. Without files the object comes without returnLabel; with files=1 the label or the 2D code is included. 404 not_found when the shipment has no return.

Field	Type	Description
`trackingNumber`, `returnTrackingNumber`	`string`	Outbound and return LDV
`status`	`string`	`pending` — booked, not scanned yet; `billed` — Poste scanned it, the return became a shipment of its own; `failed` — see `error`; `issued` — a round-trip return issued before returns were tracked
`automatic`	`boolean`	Booked by the platform when the shipment was created (account option); it prints as the second page of the label
`roundTrip`	`boolean`	The return of an Andata & Ritorno: paid with the outbound shipment, tracked the same way but never charged
`channel`, `paperless`	`string\|null`, `boolean`
`estimatedPrice`	`number\|null`	Charged only if the return is used
`firstEventAt`, `lastCheckedAt`	`datetime\|null`	First Poste scan and last tracking check
`billedShipment`	`object\|null`	Once `billed`: `{ id, trackingNumber, cost, manifestId }` of the return shipment, which has its own tracking
`error`, `warning`	`string\|null`	Poste messages about the return
`returnLabel`	`object\|null`	With `files=1`

Once a return is billed, follow it like any shipment with GET /shipments/{returnTrackingNumber}/tracking.