Domestic Order (Return)

POST 
/auth/api/v1/orders/order-create

What Is a Return Order?

A return order involves picking up a shipment from the end customer and delivering it back to the client's warehouse or another designated location.

This API allows you to initiate a domestic return by providing the necessary pickup and return details.

warning

The Return API supports domestic orders only. International return shipments are not supported through this endpoint.

This guide covers how to create a domestic return order via the Return API.

⚠️ Important: Provide the location name registered with Logistiq in the return_info_name field.

Optional but Recommended Fields

The following fields are optional in the schema but strongly recommended to ensure smoother pickups and better customer experience:

Field	Purpose
customer_email	Enables shipment tracking and return updates to the customer.
customer_phone	Facilitates SMS notifications and pickup coordination.
delivery_instructions	Improves first-attempt pickup success rate.

💡 Tip: Including these fields can significantly enhance operational reliability and customer satisfaction.

Mandatory National Address Fields (Saudi Arabia Regulation)

As per the Saudi National Address regulation, every eCommerce shipment must include the recipient’s complete and accurate national address. Providing these fields ensures legal compliance, frictionless delivery, reduced failed attempts, and faster service-level performance.

Field	Purpose
customer_city (required)	Customer city name
customer_building_number	Identifies the exact building or villa number required for precise delivery location.
customer_street_name	Ensures the address matches the official national address structure and helps courier navigation.
customer_postal_code	Defines the neighborhood or area to correctly route the shipment to the right distribution zone.
customer_zip_code	Provides the official 5-digit postal code required by Saudi regulatory standards.
customer_additional_number	Supports address verification and helps pinpoint the exact delivery point within a building block.
customer_unit_number	Specifies the apartment, office, or unit number to prevent courier/customer friction.
short_address	a code represents the national address in a short form.

Short Address Field

Optional field: Can be included in the order booking API request.

• Format: 8-character alphanumeric string.
• First 4 characters must be letters (A-Z, case-insensitive).
• Last 4 characters must be digits (0-9).
• Special characters are not allowed.
• No spaces allowed anywhere in the value.
• Leading and trailing spaces will be automatically trimmed.

💡 Tip: Ensure the value matches the pattern AAAA9999 for successful validation.

---

🇸🇦 Note: Starting January 2025, carriers in Saudi Arabia are obligated to validate and store the full national address. Providing these fields will significantly reduce delays, misrouted shipments, and failed delivery attempts.

Responses

200

Order created successfully or forwarded to workflow handler

400

Validation error or order processing failure

401

Authentication credentials were not provided