Create return order
curl --request POST \
--url https://api.orbita.melonn.com/buyer-return-orders/v2 \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"parent_external_order_number": "EXT-123",
"buyer_return_order_shipping_method_code": 1,
"transport_request_type": "async",
"external_order_number": "test-public-api-001",
"external_order_id": "1",
"buyer": {
"full_name": "Jane Doe",
"phone_number": "+573123456789",
"email": "buyer@example.com"
},
"comments": "Customer reported wrong size",
"pickup_info": {
"full_name": "Jane Doe",
"identification_number": "1000000",
"address_l1": "CRA 12 A # 145 A - 22",
"address_l2": "Apto 301",
"city": "Bogota",
"region": "Cundinamarca",
"country": "Colombia",
"postal_code": "110111",
"phone_number": "+573123456789",
"pickup_date": "2025-01-31T00:00:00.000Z"
},
"line_items": [
{
"sku": "AAABC-2-J0013-L0027-1723-M",
"qty_returned": 1,
"buyer_return_reason_code": 1,
"buyer_return_item_action_code": 1,
"return_comments": "Too small"
}
]
}
'import requests
url = "https://api.orbita.melonn.com/buyer-return-orders/v2"
payload = {
"parent_external_order_number": "EXT-123",
"buyer_return_order_shipping_method_code": 1,
"transport_request_type": "async",
"external_order_number": "test-public-api-001",
"external_order_id": "1",
"buyer": {
"full_name": "Jane Doe",
"phone_number": "+573123456789",
"email": "buyer@example.com"
},
"comments": "Customer reported wrong size",
"pickup_info": {
"full_name": "Jane Doe",
"identification_number": "1000000",
"address_l1": "CRA 12 A # 145 A - 22",
"address_l2": "Apto 301",
"city": "Bogota",
"region": "Cundinamarca",
"country": "Colombia",
"postal_code": "110111",
"phone_number": "+573123456789",
"pickup_date": "2025-01-31T00:00:00.000Z"
},
"line_items": [
{
"sku": "AAABC-2-J0013-L0027-1723-M",
"qty_returned": 1,
"buyer_return_reason_code": 1,
"buyer_return_item_action_code": 1,
"return_comments": "Too small"
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
parent_external_order_number: 'EXT-123',
buyer_return_order_shipping_method_code: 1,
transport_request_type: 'async',
external_order_number: 'test-public-api-001',
external_order_id: '1',
buyer: {
full_name: 'Jane Doe',
phone_number: '+573123456789',
email: 'buyer@example.com'
},
comments: 'Customer reported wrong size',
pickup_info: {
full_name: 'Jane Doe',
identification_number: '1000000',
address_l1: 'CRA 12 A # 145 A - 22',
address_l2: 'Apto 301',
city: 'Bogota',
region: 'Cundinamarca',
country: 'Colombia',
postal_code: '110111',
phone_number: '+573123456789',
pickup_date: '2025-01-31T00:00:00.000Z'
},
line_items: [
{
sku: 'AAABC-2-J0013-L0027-1723-M',
qty_returned: 1,
buyer_return_reason_code: 1,
buyer_return_item_action_code: 1,
return_comments: 'Too small'
}
]
})
};
fetch('https://api.orbita.melonn.com/buyer-return-orders/v2', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbita.melonn.com/buyer-return-orders/v2",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'parent_external_order_number' => 'EXT-123',
'buyer_return_order_shipping_method_code' => 1,
'transport_request_type' => 'async',
'external_order_number' => 'test-public-api-001',
'external_order_id' => '1',
'buyer' => [
'full_name' => 'Jane Doe',
'phone_number' => '+573123456789',
'email' => 'buyer@example.com'
],
'comments' => 'Customer reported wrong size',
'pickup_info' => [
'full_name' => 'Jane Doe',
'identification_number' => '1000000',
'address_l1' => 'CRA 12 A # 145 A - 22',
'address_l2' => 'Apto 301',
'city' => 'Bogota',
'region' => 'Cundinamarca',
'country' => 'Colombia',
'postal_code' => '110111',
'phone_number' => '+573123456789',
'pickup_date' => '2025-01-31T00:00:00.000Z'
],
'line_items' => [
[
'sku' => 'AAABC-2-J0013-L0027-1723-M',
'qty_returned' => 1,
'buyer_return_reason_code' => 1,
'buyer_return_item_action_code' => 1,
'return_comments' => 'Too small'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbita.melonn.com/buyer-return-orders/v2"
payload := strings.NewReader("{\n \"parent_external_order_number\": \"EXT-123\",\n \"buyer_return_order_shipping_method_code\": 1,\n \"transport_request_type\": \"async\",\n \"external_order_number\": \"test-public-api-001\",\n \"external_order_id\": \"1\",\n \"buyer\": {\n \"full_name\": \"Jane Doe\",\n \"phone_number\": \"+573123456789\",\n \"email\": \"buyer@example.com\"\n },\n \"comments\": \"Customer reported wrong size\",\n \"pickup_info\": {\n \"full_name\": \"Jane Doe\",\n \"identification_number\": \"1000000\",\n \"address_l1\": \"CRA 12 A # 145 A - 22\",\n \"address_l2\": \"Apto 301\",\n \"city\": \"Bogota\",\n \"region\": \"Cundinamarca\",\n \"country\": \"Colombia\",\n \"postal_code\": \"110111\",\n \"phone_number\": \"+573123456789\",\n \"pickup_date\": \"2025-01-31T00:00:00.000Z\"\n },\n \"line_items\": [\n {\n \"sku\": \"AAABC-2-J0013-L0027-1723-M\",\n \"qty_returned\": 1,\n \"buyer_return_reason_code\": 1,\n \"buyer_return_item_action_code\": 1,\n \"return_comments\": \"Too small\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbita.melonn.com/buyer-return-orders/v2")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"parent_external_order_number\": \"EXT-123\",\n \"buyer_return_order_shipping_method_code\": 1,\n \"transport_request_type\": \"async\",\n \"external_order_number\": \"test-public-api-001\",\n \"external_order_id\": \"1\",\n \"buyer\": {\n \"full_name\": \"Jane Doe\",\n \"phone_number\": \"+573123456789\",\n \"email\": \"buyer@example.com\"\n },\n \"comments\": \"Customer reported wrong size\",\n \"pickup_info\": {\n \"full_name\": \"Jane Doe\",\n \"identification_number\": \"1000000\",\n \"address_l1\": \"CRA 12 A # 145 A - 22\",\n \"address_l2\": \"Apto 301\",\n \"city\": \"Bogota\",\n \"region\": \"Cundinamarca\",\n \"country\": \"Colombia\",\n \"postal_code\": \"110111\",\n \"phone_number\": \"+573123456789\",\n \"pickup_date\": \"2025-01-31T00:00:00.000Z\"\n },\n \"line_items\": [\n {\n \"sku\": \"AAABC-2-J0013-L0027-1723-M\",\n \"qty_returned\": 1,\n \"buyer_return_reason_code\": 1,\n \"buyer_return_item_action_code\": 1,\n \"return_comments\": \"Too small\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbita.melonn.com/buyer-return-orders/v2")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"parent_external_order_number\": \"EXT-123\",\n \"buyer_return_order_shipping_method_code\": 1,\n \"transport_request_type\": \"async\",\n \"external_order_number\": \"test-public-api-001\",\n \"external_order_id\": \"1\",\n \"buyer\": {\n \"full_name\": \"Jane Doe\",\n \"phone_number\": \"+573123456789\",\n \"email\": \"buyer@example.com\"\n },\n \"comments\": \"Customer reported wrong size\",\n \"pickup_info\": {\n \"full_name\": \"Jane Doe\",\n \"identification_number\": \"1000000\",\n \"address_l1\": \"CRA 12 A # 145 A - 22\",\n \"address_l2\": \"Apto 301\",\n \"city\": \"Bogota\",\n \"region\": \"Cundinamarca\",\n \"country\": \"Colombia\",\n \"postal_code\": \"110111\",\n \"phone_number\": \"+573123456789\",\n \"pickup_date\": \"2025-01-31T00:00:00.000Z\"\n },\n \"line_items\": [\n {\n \"sku\": \"AAABC-2-J0013-L0027-1723-M\",\n \"qty_returned\": 1,\n \"buyer_return_reason_code\": 1,\n \"buyer_return_item_action_code\": 1,\n \"return_comments\": \"Too small\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": 527,
"internal_order_number": "R00527",
"external_order_number": "test-public-api-001",
"external_order_id": "1",
"assigned_warehouse_code": "WCOD-1",
"buyer_full_name": "Jane Doe",
"creation_date": "2025-12-01T16:16:13.000Z",
"last_modified_date": "2025-12-01T16:16:13.000Z",
"return_full_label_url": "https://example-bucket.s3.amazonaws.com/R00527-melonn-full-label.pdf?X-Amz-Expires=259200&X-Amz-Signature=...",
"buyer_return_order_state": {
"code": 1,
"closed": false,
"description": "Created"
},
"line_items_summary": [
{
"sku": "AAABC-2-J0013-L0027-1723-M",
"qty_returned": 1,
"content": [],
"composite": false
}
],
"parent_sell_order": {
"internal_order_number": "S1234567890",
"external_order_number": "EXT-123",
"external_order_id": "123"
}
}Buyer return orders
Create return order
Creates a buyer return order from an existing Melonn sell order (the parent sell order).
How it works
- The parent sell order is looked up by
parent_external_order_numberamong your sell orders, including closed ones. When you sendecommerce_store_id, the order is first searched in that store. - Each
skuinline_itemsmust exist in your catalog (matched case-insensitively). If a SKU is a kit, the return is recorded against its components; the response keeps the kit and lists its components incontent. - The return is received at
assigned_warehouse_codeif you send it; otherwise at the warehouse that fulfilled the parent sell order. - The order is created in state
1(Created). Its Melonn identifier,internal_order_number(e.g.R00527), is in the response: use it to get or cancel the return.
Shipping methods (buyer_return_order_shipping_method_code)
| Code | Method | What happens |
|---|---|---|
| 1 | Collected by Melonn | Melonn requests a carrier to pick up the package at pickup_info’s address. The address must be geocodable. The carrier label is produced asynchronously; see transport_request_type. |
| 2 | Shipped by the buyer | The buyer sends the package to the warehouse. A Melonn return label is generated during creation. |
| 3 | Dropped off at Melonn | The buyer drops the package off at the warehouse. A Melonn return label is generated during creation. |
Return label. return_full_label_url is a pre-signed download link to the return
label PDF, valid for 72 hours (3 days) from the moment of the response. It is an empty
string when the label is not ready yet. With shipping method 1 and the default
transport_request_type (async) the label is not ready at creation time; use
Get return order later to obtain it.
With transport_request_type: sync the request waits up to about 10 seconds for the
carrier label before answering.
Request body. Unknown fields are silently ignored (they are stripped before processing, not rejected).
POST
/
buyer-return-orders
/
v2
Create return order
curl --request POST \
--url https://api.orbita.melonn.com/buyer-return-orders/v2 \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"parent_external_order_number": "EXT-123",
"buyer_return_order_shipping_method_code": 1,
"transport_request_type": "async",
"external_order_number": "test-public-api-001",
"external_order_id": "1",
"buyer": {
"full_name": "Jane Doe",
"phone_number": "+573123456789",
"email": "buyer@example.com"
},
"comments": "Customer reported wrong size",
"pickup_info": {
"full_name": "Jane Doe",
"identification_number": "1000000",
"address_l1": "CRA 12 A # 145 A - 22",
"address_l2": "Apto 301",
"city": "Bogota",
"region": "Cundinamarca",
"country": "Colombia",
"postal_code": "110111",
"phone_number": "+573123456789",
"pickup_date": "2025-01-31T00:00:00.000Z"
},
"line_items": [
{
"sku": "AAABC-2-J0013-L0027-1723-M",
"qty_returned": 1,
"buyer_return_reason_code": 1,
"buyer_return_item_action_code": 1,
"return_comments": "Too small"
}
]
}
'import requests
url = "https://api.orbita.melonn.com/buyer-return-orders/v2"
payload = {
"parent_external_order_number": "EXT-123",
"buyer_return_order_shipping_method_code": 1,
"transport_request_type": "async",
"external_order_number": "test-public-api-001",
"external_order_id": "1",
"buyer": {
"full_name": "Jane Doe",
"phone_number": "+573123456789",
"email": "buyer@example.com"
},
"comments": "Customer reported wrong size",
"pickup_info": {
"full_name": "Jane Doe",
"identification_number": "1000000",
"address_l1": "CRA 12 A # 145 A - 22",
"address_l2": "Apto 301",
"city": "Bogota",
"region": "Cundinamarca",
"country": "Colombia",
"postal_code": "110111",
"phone_number": "+573123456789",
"pickup_date": "2025-01-31T00:00:00.000Z"
},
"line_items": [
{
"sku": "AAABC-2-J0013-L0027-1723-M",
"qty_returned": 1,
"buyer_return_reason_code": 1,
"buyer_return_item_action_code": 1,
"return_comments": "Too small"
}
]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
parent_external_order_number: 'EXT-123',
buyer_return_order_shipping_method_code: 1,
transport_request_type: 'async',
external_order_number: 'test-public-api-001',
external_order_id: '1',
buyer: {
full_name: 'Jane Doe',
phone_number: '+573123456789',
email: 'buyer@example.com'
},
comments: 'Customer reported wrong size',
pickup_info: {
full_name: 'Jane Doe',
identification_number: '1000000',
address_l1: 'CRA 12 A # 145 A - 22',
address_l2: 'Apto 301',
city: 'Bogota',
region: 'Cundinamarca',
country: 'Colombia',
postal_code: '110111',
phone_number: '+573123456789',
pickup_date: '2025-01-31T00:00:00.000Z'
},
line_items: [
{
sku: 'AAABC-2-J0013-L0027-1723-M',
qty_returned: 1,
buyer_return_reason_code: 1,
buyer_return_item_action_code: 1,
return_comments: 'Too small'
}
]
})
};
fetch('https://api.orbita.melonn.com/buyer-return-orders/v2', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbita.melonn.com/buyer-return-orders/v2",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'parent_external_order_number' => 'EXT-123',
'buyer_return_order_shipping_method_code' => 1,
'transport_request_type' => 'async',
'external_order_number' => 'test-public-api-001',
'external_order_id' => '1',
'buyer' => [
'full_name' => 'Jane Doe',
'phone_number' => '+573123456789',
'email' => 'buyer@example.com'
],
'comments' => 'Customer reported wrong size',
'pickup_info' => [
'full_name' => 'Jane Doe',
'identification_number' => '1000000',
'address_l1' => 'CRA 12 A # 145 A - 22',
'address_l2' => 'Apto 301',
'city' => 'Bogota',
'region' => 'Cundinamarca',
'country' => 'Colombia',
'postal_code' => '110111',
'phone_number' => '+573123456789',
'pickup_date' => '2025-01-31T00:00:00.000Z'
],
'line_items' => [
[
'sku' => 'AAABC-2-J0013-L0027-1723-M',
'qty_returned' => 1,
'buyer_return_reason_code' => 1,
'buyer_return_item_action_code' => 1,
'return_comments' => 'Too small'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbita.melonn.com/buyer-return-orders/v2"
payload := strings.NewReader("{\n \"parent_external_order_number\": \"EXT-123\",\n \"buyer_return_order_shipping_method_code\": 1,\n \"transport_request_type\": \"async\",\n \"external_order_number\": \"test-public-api-001\",\n \"external_order_id\": \"1\",\n \"buyer\": {\n \"full_name\": \"Jane Doe\",\n \"phone_number\": \"+573123456789\",\n \"email\": \"buyer@example.com\"\n },\n \"comments\": \"Customer reported wrong size\",\n \"pickup_info\": {\n \"full_name\": \"Jane Doe\",\n \"identification_number\": \"1000000\",\n \"address_l1\": \"CRA 12 A # 145 A - 22\",\n \"address_l2\": \"Apto 301\",\n \"city\": \"Bogota\",\n \"region\": \"Cundinamarca\",\n \"country\": \"Colombia\",\n \"postal_code\": \"110111\",\n \"phone_number\": \"+573123456789\",\n \"pickup_date\": \"2025-01-31T00:00:00.000Z\"\n },\n \"line_items\": [\n {\n \"sku\": \"AAABC-2-J0013-L0027-1723-M\",\n \"qty_returned\": 1,\n \"buyer_return_reason_code\": 1,\n \"buyer_return_item_action_code\": 1,\n \"return_comments\": \"Too small\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbita.melonn.com/buyer-return-orders/v2")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"parent_external_order_number\": \"EXT-123\",\n \"buyer_return_order_shipping_method_code\": 1,\n \"transport_request_type\": \"async\",\n \"external_order_number\": \"test-public-api-001\",\n \"external_order_id\": \"1\",\n \"buyer\": {\n \"full_name\": \"Jane Doe\",\n \"phone_number\": \"+573123456789\",\n \"email\": \"buyer@example.com\"\n },\n \"comments\": \"Customer reported wrong size\",\n \"pickup_info\": {\n \"full_name\": \"Jane Doe\",\n \"identification_number\": \"1000000\",\n \"address_l1\": \"CRA 12 A # 145 A - 22\",\n \"address_l2\": \"Apto 301\",\n \"city\": \"Bogota\",\n \"region\": \"Cundinamarca\",\n \"country\": \"Colombia\",\n \"postal_code\": \"110111\",\n \"phone_number\": \"+573123456789\",\n \"pickup_date\": \"2025-01-31T00:00:00.000Z\"\n },\n \"line_items\": [\n {\n \"sku\": \"AAABC-2-J0013-L0027-1723-M\",\n \"qty_returned\": 1,\n \"buyer_return_reason_code\": 1,\n \"buyer_return_item_action_code\": 1,\n \"return_comments\": \"Too small\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbita.melonn.com/buyer-return-orders/v2")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"parent_external_order_number\": \"EXT-123\",\n \"buyer_return_order_shipping_method_code\": 1,\n \"transport_request_type\": \"async\",\n \"external_order_number\": \"test-public-api-001\",\n \"external_order_id\": \"1\",\n \"buyer\": {\n \"full_name\": \"Jane Doe\",\n \"phone_number\": \"+573123456789\",\n \"email\": \"buyer@example.com\"\n },\n \"comments\": \"Customer reported wrong size\",\n \"pickup_info\": {\n \"full_name\": \"Jane Doe\",\n \"identification_number\": \"1000000\",\n \"address_l1\": \"CRA 12 A # 145 A - 22\",\n \"address_l2\": \"Apto 301\",\n \"city\": \"Bogota\",\n \"region\": \"Cundinamarca\",\n \"country\": \"Colombia\",\n \"postal_code\": \"110111\",\n \"phone_number\": \"+573123456789\",\n \"pickup_date\": \"2025-01-31T00:00:00.000Z\"\n },\n \"line_items\": [\n {\n \"sku\": \"AAABC-2-J0013-L0027-1723-M\",\n \"qty_returned\": 1,\n \"buyer_return_reason_code\": 1,\n \"buyer_return_item_action_code\": 1,\n \"return_comments\": \"Too small\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": 527,
"internal_order_number": "R00527",
"external_order_number": "test-public-api-001",
"external_order_id": "1",
"assigned_warehouse_code": "WCOD-1",
"buyer_full_name": "Jane Doe",
"creation_date": "2025-12-01T16:16:13.000Z",
"last_modified_date": "2025-12-01T16:16:13.000Z",
"return_full_label_url": "https://example-bucket.s3.amazonaws.com/R00527-melonn-full-label.pdf?X-Amz-Expires=259200&X-Amz-Signature=...",
"buyer_return_order_state": {
"code": 1,
"closed": false,
"description": "Created"
},
"line_items_summary": [
{
"sku": "AAABC-2-J0013-L0027-1723-M",
"qty_returned": 1,
"content": [],
"composite": false
}
],
"parent_sell_order": {
"internal_order_number": "S1234567890",
"external_order_number": "EXT-123",
"external_order_id": "123"
}
}Authorizations
Body
application/json
External order number of the sell order being returned (the parent sell order), as you sent it when creating that sell order.
Example:
"EXT-123"
How the package travels back to Melonn:
1: Collected by Melonn (a carrier picks it up atpickup_info's address).2: Shipped by the buyer.3: Dropped off at Melonn by the buyer.
Available options:
1, 2, 3 Example:
1
Your identifier for the return. Shown in Melonn and usable as a filter in List return orders.
Example:
"test-public-api-001"
The buyer who is returning the products.
Show child attributes
Show child attributes
Where and from whom the package is collected. Required for every shipping method, but only used for pickup when buyer_return_order_shipping_method_code is 1; in that case the address must be geocodable.
Show child attributes
Show child attributes
Products being returned. At least one.
Minimum array length:
1Show child attributes
Show child attributes
Only relevant for shipping method 1. With sync, the request waits up to about 10 seconds for the carrier pickup to be booked and returns its label in return_full_label_url (empty if it was not ready in time). With async or when omitted, the request returns immediately and the label becomes available later through Get return order.
Available options:
sync, async Example:
"async"
Optional secondary identifier for the return in your system. Must be unique per e-commerce store.
Example:
"1"
ID of your e-commerce store (sales channel) in Melonn. When sent, the parent sell order is looked up in this store first, and the return is linked to it.
Example:
12
Code of the warehouse that will receive the return. Defaults to the warehouse that fulfilled the parent sell order.
Example:
"WCOD-1"
Free-text comments about the return.
Example:
"Customer reported wrong size"
Response
The return order was created.
Numeric Melonn ID of the return order.
Example:
527
Melonn internal order number of the return order. Use it to get or cancel the return.
Example:
"R00527"
Your identifier for the return, as sent on creation.
Example:
"test-public-api-001"
Your secondary identifier for the return, or null if none was sent.
Example:
null
Code of the warehouse that receives the return.
Example:
"WCOD-1"
Full name of the buyer.
Example:
"Jane Doe"
When the return order was created (UTC).
Example:
"2025-12-01T16:16:13.000Z"
When the return order was last modified (UTC).
Example:
"2025-12-01T16:16:13.000Z"
Current state of the return order.
| Code | State | Closed |
|---|---|---|
| 1 | Created | No |
| 2 | Canceled | Yes |
| 3 | In transit | No |
| 4 | Received | No |
| 5 | Processing | No |
| 6 | Processed | Yes |
| 7 | Transport service requested | No |
| 8 | Delivered at warehouse by transport service | No |
Show child attributes
Show child attributes
Pre-signed download link to the return label PDF, valid for 72 hours (3 days) from the response. Empty string when the label is not ready yet.
Example:
"https://example-bucket.s3.amazonaws.com/R00527-melonn-full-label.pdf?X-Amz-Expires=259200&X-Amz-Signature=..."
Returned products, as requested (kits are kept as kits).
Show child attributes
Show child attributes
The sell order this return was created from.
Show child attributes
Show child attributes