Return Shipment

Create a reverse shipment for a delivered order using a selected courier service. This endpoint validates the order eligibility, courier restrictions, and wallet balance, then creates the reverse shipment, debits the wallet if needed, and generates a return label.

📌

Authentication

Requires Bearer token authentication.

Only orders that the authenticated user is allowed to manage (delivered orders for this merchant/warehouse) can be used to create a reverse shipment.

📌

Behavior

Validates that the order exists and is eligible for a reverse shipment (for example, in delivered status).

Ensures that the requested courier is allowed for reverse shipments of this order.

Computes the reverse shipment rate and checks the user wallet balance.

When shipment_package is provided, it is used as the package parameter when creating the shipment; otherwise, the system uses the associated order box (orderPackage).

💡

Calls the configured courier integration to create the reverse shipment; errors from the courier or integration layer produce a 422 response.

Generates a reverse shipping label PDF and returns the latest shipment details (tracking link, label URL, costs, courier, external ID) along with the updated order status.

Request

Authorization

OAuth 2.0

Client Credentials

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Token URL: https://app.gotreek.com/api/auth/login

Header Params

Body Params application/jsonRequired

Examples

curl --location --request POST 'https://app.gotreek.com/api/shipments/reverse-Shipment' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "order_id": 0, "courier": "string", "shipment_packages": [ { "length": 1, "width": 1, "height": 1, "weight": 1 }, { "length": 1, "width": 1, "height": 1, "weight": 1 } ], "use_global_config": true }'

{ "success": true, "message": "Reverse shipment created successfully.", "data": { "shipment_id": 23167, "tracking_link": "https://www.aramex.com/sa/ar/track/results?ShipmentNumber=50597390686", "shipment_label_url": null, "shipment_cost": 1900, "shipment_cost_without_cod": 1900, "order_status": "returned", "courier": "aramex", "external_id": "50597390686" } }

Request

Responses