Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Light Return for international shipments within Europe

Create Light Return Shipment

post
/shipments/light-return

Creates a return shipment after the original order has been delivered. This method allows customers to create a return shipment after delivery — regardless of who handled the last mile (Nova Post or a partner).

Supported shipment direction:

  • Europe → Europe (including Moldova → Romania)

ℹ️ Information: To allow this request to work, the account manager must enable the LightReturn setting on the legal entity in the internal Nova Post system. Once this setting is activated, the request will function via API on new delivered shipments. The return can be created only if the parent shipment has the Delivered status and includes the AllowedLightReturn service. The current status of a shipment can be found in the "items" → "statusCode" field of the Find documents method. AllowedLightReturn defines the number of days within which the recipient can initiate a return after the delivery. Internally, the system verifies several conditions before allowing a Light Return shipment to be created:

  • The parent shipment status must be one of: Issued (9, 10, 11, 106).

  • The system calculates the allowed return period using the following logic: finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 day where returnDays is taken from the AllowedLightReturn service, and toTZ applies the relevant system time zone (e.g., EU region).

  • The return can be created only if the current time (nowTZ) is earlier than finalDate.

  • The system also checks that no Light Return has already been created for the same parent shipment.

If all these conditions are met, the return creation request is accepted; otherwise, the system responds with a validation error indicating why the return is not permitted.

How the Light Return Shipment works (Europe → Europe)

  • The request must include one required parameter — number (the parent shipment number). All other parameters are optional.

  • If optional parameters are not specified, their values are automatically inherited from the parent shipment whenever possible.

  • The customer can hand over the return shipment at a Nova Post branch or use courier pickup.

  • If the parent delivery was made to a parcel locker, PUDO, or an address, the nearest available Nova Post branch is selected automatically.

  • Customers may specify a valid branch directly in the request.

  • Parcel lockers and PUDO cannot be used as return handover locations.

When the return is created, the system automatically generates a return waybill. For more information on printing the return label, see Print Shipment Documents. For more information on creating a parent shipment, see Create documents.

🔹Description of control elements:

SCHEMA

Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.

  • Single line description A description that fits into a single line; any text that does not fit remains hidden.

  • Multiline description An expanded description that displays more than one line of text.

EXAMPLE

Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

Authorizations
AuthorizationstringRequired

Authorization JWT-token with a lifetime of 1 hour in header

Body
numberstringRequired

The number of the parent shipment for which the return is initiated. This parameter is mandatory to create a return.

Example: SHMD0000000000
divisionIdstringOptional

Identifier of the division that will process the return.

🔹This field is optional.

Example: 1835903
senderPhonestringOptional

Phone number of the sender for the return shipment.

🔹Required if acting as a third person.

Example: 490000000000
payerTypestring · enumOptional

Specifies who pays for the return shipment.

🔹If not specified, the default value is Recipient

🔹Supported only for Europe → Europe Light Return shipments.

Possible values:
payerContractNumberstringOptional

Contract number of the payer.

Rules:

  • Required when payerType = ThirdPerson.
  • Optional for Recipient if the parent shipment used contract payment.
Responses
200

Successfully created Light Return shipment.

application/json
objectOptional
post/shipments/light-return

Last updated