> For the complete documentation index, see [llms.txt](https://api-portal.novapost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-portal.novapost.com/metodi-1/methods/shipments/return/light-return-for-cross-border-shipments-from-ukraine-to-europe.md). # Light Return for cross-border shipments from Ukraine to Europe ## Create Light Return Shipment > 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.
```json {"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Shipments"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/shipments/light-return":{"post":{"tags":["Shipments"],"summary":"Create Light Return Shipment","description":"Creates a return after the original shipment has been delivered.\n\nℹ️ **Information:**
\nTo allow this request to work, the account manager must enable the LightReturn setting on the legal entity in the internal Nova Post system.
\nOnce this setting is activated, the request will function via API on new delivered shipments.\nThe return can be created only if the parent shipment has the **Delivered** status and includes the **AllowedLightReturn** service.
\nThe current status of a shipment can be found in the `\"items\" → \"statusCode\"` field of the [Find documents](https://api-portal.novapost.com/metodi-1/methods/shipments#get-shipments) method.
\n**AllowedLightReturn** defines the number of days within which the recipient can initiate a return after the delivery.\nInternally, the system verifies several conditions before allowing a Light Return shipment to be created:\n- The parent shipment status must be one of: `Issued (9, 10, 11, 106)`.\n- The system calculates the allowed return period using the following logic:
\n `finalDate = toTZ(parentShipment.RecipientDateTime) + returnDays + 1 day`
\n where returnDays is taken from the AllowedLightReturn service, and toTZ applies the relevant system time zone (e.g., EU region).\n- The return can be created only if the current time (nowTZ) is earlier than finalDate.\n- The system also checks that no Light Return has already been created for the same parent shipment.\n\nIf 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.\n\n**How the Light Return Shipment works (Ukraine → Europe)**\n\n- The request must include one required parameter — `number` (the parent shipment number). All other parameters are optional.\n- Two return scenarios are supported:\n - **Full Return** – only the `number` parameter is required. All shipment data is inherited from the parent shipment.\n - **Partial Return** – additional shipment data (such as `invoice` and `parcels`) can be provided to return only selected goods or update parcel dimensions.\n- If optional parameters are not specified, their values are automatically inherited from the parent shipment whenever possible.\n- Only Nova Post branches are allowed as return handover locations.\n- If the parent delivery was made to an APM (parcel locker), PUDO, or an address, the nearest available Nova Post branch is selected automatically.\n- Customers may specify a valid `divisionId` directly in the request.\n- Courier pickup, APMs (parcel lockers), and PUDO cannot be used as return handover locations.\n\n**Partial Return**\n\nFor Partial Returns:\n- All values in `invoice.items[]` must exactly match the corresponding items from the parent shipment.\n- Creating new invoice items or modifying existing item values is not allowed.\n- The initiating client is responsible for ensuring consistency between `amount`, `cost`, and `actualWeight`.\n- To avoid validation errors, it is recommended to copy invoice data directly from the parent shipment.\n\nWhen the return is created, the system automatically generates a return waybill.
\nFor more information on printing the return label, see [Print Shipment Documents](https://api-portal.novapost.com/metodi-1/methods/shipments/print-documents#get-shipments-print).
\nFor more information on creating a parent shipment, see [Create documents](https://api-portal.novapost.com/metodi-1/methods/shipments/create-shipments).\n\n🔹**Description of control elements:**\n\n**SCHEMA**\n\nDisplays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.\n- **Single line description**
\n A description that fits into a single line; any text that does not fit remains hidden.\n- **Multiline description**
\n An expanded description that displays more than one line of text.\n\n**EXAMPLE**\n\nShows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["number"],"properties":{"number":{"type":"string","description":"The number of the **parent shipment** for which the return is initiated.\nThis parameter is mandatory to create a return.\n"},"divisionId":{"type":"string","description":"Identifier of the division that will process the return.\n\n**🔹This field is optional.**\n"},"sender":{"type":"object","description":"Sender information for the return shipment.","properties":{"divisionId":{"type":"string","description":"Identifier of the Nova Post branch in Ukraine where the return shipment will be handed over."},"senderPhone":{"type":"string","description":"Phone number of the sender for the return shipment.\n"},"addressParts":{"type":"object","description":"Structure describing the courier pickup address.\n\n🔹Used if `divisionId` is not provided.\n","properties":{"countryCode":{"type":"string","description":"Country code according to ISO 3166-1 alpha-2."},"city":{"type":"string","description":"City name of the pickup address."},"region":{"type":"string","description":"Region or administrative area of the address."},"street":{"type":"string","description":"Street name of the pickup address."},"postCode":{"type":"string","description":"Postal code of the pickup address."},"building":{"type":"string","description":"Building number of the pickup address."},"flat":{"type":"string","description":"Apartment or office number at the specified address."},"block":{"type":"string","description":"Block or section information for the address, if applicable."},"note":{"type":"string","description":"Additional details or notes for the address (e.g., entrance, floor, or courier instructions)."}}}}},"recipient":{"type":"object","description":"Recipient information for the return shipment.","properties":{"divisionId":{"type":"string","description":"Identifier of the Nova Post branch where the return shipment will be delivered."},"addressParts":{"type":"object","description":"Structure describing the delivery address.\n\n🔹Used if `divisionId` is not provided.\n","properties":{"countryCode":{"type":"string","description":"Country code according to ISO 3166-1 alpha-2."},"city":{"type":"string","description":"City name of the delivery address."},"region":{"type":"string","description":"Region or administrative area of the address."},"street":{"type":"string","description":"Street name of the delivery address."},"postCode":{"type":"string","description":"Postal code of the delivery address."},"building":{"type":"string","description":"Building number of the delivery address."},"flat":{"type":"string","description":"Apartment or office number at the specified address."},"block":{"type":"string","description":"Block or section information for the address, if applicable."},"note":{"type":"string","description":"Additional details or notes for the address (e.g., entrance, floor, or delivery instructions)."}}}}},"invoice":{"type":"object","description":"This object presents the necessary data for customs authorities to process the consignment efficiently, including the assessment of duties and taxes, and to confirm adherence to import/export regulations. The structured format of the invoice ensures that all pertinent information is easily accessible and clear, facilitating a smoother transit across borders.\n\n🔹For Partial Returns, all values in `invoice.items[]` must match the corresponding items from the parent shipment. Creating new items or modifying existing values is not allowed.\n","properties":{"incoterm":{"type":"string","description":"Specifies the trade terms based on Incoterms® (e.g., DAP). Required for cross-border shipments.","enum":["DAP"]},"currencyCode":{"type":"string","description":"ISO 4217 currency code of the invoice. All items in the invoice must use the same currency.","pattern":"^[A-Z]{3}$"},"exportReason":{"type":"string","description":"Reason for export (ForPersonalPurposes, Selling, Repair, Return, Other).","enum":["ForPersonalPurposes","Selling","Repair","Return","Other"]},"totalCost":{"type":"number","description":"Total declared invoice value in the original currency, which must equal the sum of all invoice items calculated as **(amount × cost)** for each item.","minimum":1,"maximum":9999999.99},"items":{"type":"array","description":"Detailed list of goods being shipped, required for customs declaration.\n\n🔹For Partial Returns, all item values must match the corresponding items from the parent shipment.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Item name in the local language."},"nameEng":{"type":"string","description":"Item name in English."},"measurementCode":{"type":"string","description":"Unit of measurement (e.g., pcs, kg, m)."},"hsCode":{"type":"string","description":"Harmonized System code for each item (8–10 digits)."},"amount":{"type":"number","description":"The quantity of the item being shipped, necessary for inventory and customs documentation.\n\nFor Partial Returns, the value must remain consistent with `cost` and `actualWeight`.\n"},"cost":{"type":"number","description":"The value per single unit of the item in the sender's currency, important for insurance and customs valuation.\n\nFor Partial Returns, the value must remain consistent with `amount` and `actualWeight`.\n"},"costUsd":{"type":"number","description":"The item's value converted to US Dollars, facilitating consistent valuation in international transactions.\n\n**🔹This field is required for shipments crossing the EU border or going outside the EU.**\n","minimum":0,"maximum":9999999.99},"costEur":{"type":"number","description":"The item's value in Euros, providing a standardized currency evaluation for European trade operations.\n\n**🔹This field is required for shipments crossing the EU border or going outside the EU.**\n"},"producerAndModel":{"type":"string","description":"The parameter represents the manufacturer and model of the device. Both values are included in a single parameter. This parameter is mandatory for the following categories:\n- Electrical appliances\n- Laptops\n- Phones\n- Large and small household appliances\n- Other similar items\n\n**🔸This field is not required; however, shipments with this field filled are given priority during customs clearance.**\n"}}}}}},"parcels":{"type":"array","description":"`Parcels` description block.\nEach object contains information about one parcel in the shipment.\n","items":{"type":"object","properties":{"cargoCategory":{"type":"string","enum":["parcel","documents","pallet"],"description":"Type of shipment (parcel or documents)."},"number":{"type":"string","description":"The number of the **parent shipment** for which the return is initiated.\n\nThis parameter is mandatory to create a return.\n"},"parcelDescription":{"type":"string","description":"Short description of parcel contents."},"insuranceCost":{"type":"number","format":"float","description":"Declared insurance value of the parcel."},"untied":{"type":"boolean","description":"Indicates whether the parcel is untied.\n\nA value of `false` indicates a standard parcel, while `true` indicates an untied parcel (unsecured cargo).\n"},"width":{"type":"integer","description":"Parcel width in millimeters."},"length":{"type":"integer","description":"Parcel length in millimeters."},"height":{"type":"integer","description":"Parcel height in millimeters."},"actualWeight":{"type":"integer","description":"Actual total weight of all units of the item in grams (g)."},"volumetricWeight":{"type":"integer","description":"Parcel volumetric weight in grams (g).\n\nRetrieved from the parent shipment for return shipments.\n"}}}}}}}}},"responses":{"200":{"description":"Successfully created Light Return shipment.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized request — invalid or missing authentication token.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"403":{"description":"Parent shipment is missing the AllowedLightReturn parameter.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"404":{"description":"Parent shipment not found or status not allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"422":{"description":"Parent shipment not found or status not allowed.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}},"503":{"description":"Service unavailable or request timeout.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","properties":{"errorMessage":{"type":"string"}}}}}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api-portal.novapost.com/metodi-1/methods/shipments/return/light-return-for-cross-border-shipments-from-ukraine-to-europe.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.