Create a Return

This API allows you to create a return request in the Eshopbox system. Only customer returns can be created, and the order must be fulfilled and delivered in the Eshopbox workspace before initiating a

Endpoint

POST http://wms.eshopbox.com/api/return

Headers

Name	Type	Description
Authorization	string	Bearer Token to grant access to the API

Request Body

Name	Mandatory	Type	Description
externalChannelID	No	string	Name of the sales channel generated by Eshopbox
customerReturnNumber	Yes	string	Unique return number against a sales channel
assignCourier	Yes	boolean	true to assign return tracking ID, false if not required
customerOrderId	Yes	string	Unique order number against a sales channel (Previously customerOrderNumber)
pickup_type	Yes	string	Pickup type for return, default: "reverse"
refundAmount	Yes	string	Amount to be refunded on the return request
isCOD	Yes	boolean	true if the order is Cash on Delivery (COD), false if prepaid. Since we are created return, if will be false.
return_request_date	Yes	string	Return request date and time (cannot be NULL, even though it's optional)
repaymentType	No	string	Refund mode

Pickup Address (Object)

Name	Mandatory	Type	Description
customerName	Yes	string	Name of the pickup customer
addressLine1	Yes	string	Pickup address line 1
addressLine2	Yes	string	Pickup address line 2
city	Yes	string	Pickup address city
state	Yes	string	Pickup address state
postalCode	Yes	string	Pickup address PIN code
countryCode	Yes	string	Pickup address country code
countryName	Yes	string	Pickup address country name
contactPhone	Yes	string	Pickup address contact number
email	Yes	string	Pickup address email address

Items (Array)

Name	Mandatory	Type	Description
lineItemSequenceNumber	No	string	Unique item ID in the client system
itemID	No	string	Product availability identifier on a channel
sku	Yes	string	SKU of the product (previously SKU)
quantity	Yes	number	Quantity of the item to be returned
returnReason	Yes	string	Reason for return
additionalInfo.image	No	string	Image shared by the customer
additionalInfo.comment	No	string	Remarks shared by the customer
itemImage	No	string	Product image

Response

200 Return successfully created.

{
    "externalChannelID": "CH3458",
    "integrationType": "4",
    "channelLabel": "Test123",
    "customerReturnNumber": "ReturnTestviaAPI13",
    "customerOrderNumber": "DiscrepancySmoke25",
    "pickupType": "reverse",
    "status": "CREATED",
    "latest_status": "created",
    "pickupAddress": {
        "pickup_customerName": "Gajanand Jangir",
        "pickup_addressLine1": "Near diwan hotel ajeetgarh",
        "pickup_addressLine2": "",
        "pickup_city": "SIKAR",
        "pickup_state": "",
        "pickup_postalCode": "332701",
        "pickup_countryCode": "IN",
        "pickup_countryName": "India",
        "pickup_contactPhone": "[phone]",
        "pickup_email": "[e-mail]"
    },
    "dropAddress": {
        "drop_name": "Delhi Warehouse",
        "drop_address": "68p sector 22, gurgaon",
        "drop_pincode": "122015",
        "drop_city": "Gurgaon",
        "drop_country": "India",
        "drop_state": "Haryana",
        "drop_contact": "9571912345"
    },
    "items": [
        {
            "lineItemSequenceNumber": 0,
            "orderItemID": "DiscrepancySmoke25-45102164",
            "itemID": "My4",
            "quantity": 1,
            "returnReason": "size is too small",
            "productName": "My product 4",
            "itemImage": "",
            "returnFlag": "1",
            "lineItemTotal": 1000,
            "productAdditionalInfo": {
                "specification": [
                    "enable batch tracking"
                ],
                "productDetails": {
                    "unitPrice": 1000,
                    "hsnCode": "4858645",
                    "dimensionHeight": 10,
                    "dimensionLength": 10,
                    "dimensionUnit": "cm",
                    "description": "My product 4",
                    "weight": 480,
                    "weight_dimension_status": "unverified",
                    "mrp": 2000,
                    "dimensionWidth": 10,
                    "type": "BASE",
                    "taxCode": "ESBGST2",
                    "imageUrl": "https://cdn.shopify.com/s/files/1/0698/9820/7478/files/PROD4.png?v=1750413384",
                    "accountSlug": "eshopboxdemo",
                    "sku": "My4",
                    "esin": "Y4SX63I3A45",
                    "brand": "",
                    "additionalNames": {
                        "others": [
                            "My4"
                        ]
                    },
                    "status": "ACTIVE",
                    "weightUnit": "g"
                }
            }
        }
    ],
    "trackingId": "24343321002736",
    "courierName": "XpressBees"
}

curl --location --request POST 'http://wms.eshopbox.com/api/return' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data-raw '{
    "customerReturnNumber": "RET123456",
    "assignCourier": false,
    "customerOrderId": "ORD987654",
    "externalChannelID": "SHOPIFY",
    "pickup_type": "reverse",
    "refundAmount": "1500",
    "isCOD": false,
    "return_request_date": "2025-03-19 10:30:00",
    "repaymentType": "wallet",
    "pickupAddress": {
        "customerName": "John Doe",
        "addressLine1": "123, Main Street",
        "addressLine2": "Near City Park",
        "city": "Mumbai",
        "state": "Maharashtra",
        "postalCode": "400001",
        "countryCode": "IN",
        "countryName": "India",
        "contactPhone": "9876543210",
        "email": "[e-mail]"
    },
    "items": [
        {
            "lineItemSequenceNumber": "1001",
            "itemID": "ABC12345",
            "sku": "PROD56789",
            "quantity": "1",
            "returnReason": "Defective product",
            "additionalInfo": {
                "image": "https://example.com/image1.jpg",
                "comments": "Product is not working"
            },
            "itemImage": "https://example.com/realImage.jpg"
        }
    ]
}'