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

Light Return for cross-border shipments from Ukraine to Europe

Create Light Return Shipment

post
/shipments/light-return

Creates a return after the original shipment has been delivered.

ℹ️ 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 (Ukraine → Europe)

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

  • Two return scenarios are supported:

    • Full Return – only the number parameter is required. All shipment data is inherited from the parent shipment.

    • Partial Return – additional shipment data (such as invoice and parcels) can be provided to return only selected goods or update parcel dimensions.

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

  • Only Nova Post branches are allowed as return handover locations.

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

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

  • Courier pickup, APMs (parcel lockers), and PUDO cannot be used as return handover locations.

Partial Return

For Partial Returns:

  • All values in invoice.items[] must exactly match the corresponding items from the parent shipment.

  • Creating new invoice items or modifying existing item values is not allowed.

  • The initiating client is responsible for ensuring consistency between amount, cost, and actualWeight.

  • To avoid validation errors, it is recommended to copy invoice data directly from the parent shipment.

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.

Example: 490000000000
Responses
200

Successfully created Light Return shipment.

application/json
objectOptional
post/shipments/light-return

Last updated