Returns
Create Return
Creates a Return — a Return Ticket plus its Return Shipment. Available to accounts using the Returns Experience (contact your account team to enable it).
Use this endpoint when the return request happens outside the branded returns widget; the widget creates returns itself, copying order, address, and line-item data from the outbound Shipment.
Two request shapes, one endpoint:
- Standard flow: both
return_ticketandshipmentobjects are required. The Shipment needsshipment_idand at least one line item (the item being returned). The return label is generated later by the Return Booking Service — do not sendtracking_numberorcarrier_reference. - Preprinted-label flow (label already in the outbound box;
requires the Preprinted Return Labels setting): send only the
shipmentobject.shipment_idis required; if you are NOT using Perform.AI Booking,tracking_numberandcarrier_referenceare also required.
Identical create requests are deduplicated for 30 minutes — a repeat within the window returns the original response instead of creating a duplicate.
POST
/
v5
/
return
/
Create Return
curl --request POST \
--url https://api.perform.ai/v5/return/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"return_ticket": {
"return_id": "RMA-2026-0042",
"comment": "Size is too small.",
"refund_method": "store_credit",
"return_method": "drop_off"
},
"shipment": {
"shipment_id": "SHP-RET-2026-000042",
"order_id": "ORD-2026-000114",
"line_items": [
{
"product_name": "Running Shoes",
"quantity": 1,
"currency_code": "EUR",
"product_cost": 79.99,
"return_reason": "wrong size"
}
],
"to_address": {
"first_name": "Perform",
"last_name": "Warehouse",
"line1": "12 Hafenstrasse",
"postal_code": "10115",
"city": "Berlin",
"country_code": "DE"
},
"from_address": {
"first_name": "Jane",
"last_name": "Doe",
"line1": "52 Bread Street",
"postal_code": "049145",
"city": "Singapore",
"country_code": "SG"
}
}
}
'import requests
url = "https://api.perform.ai/v5/return/"
payload = {
"return_ticket": {
"return_id": "RMA-2026-0042",
"comment": "Size is too small.",
"refund_method": "store_credit",
"return_method": "drop_off"
},
"shipment": {
"shipment_id": "SHP-RET-2026-000042",
"order_id": "ORD-2026-000114",
"line_items": [
{
"product_name": "Running Shoes",
"quantity": 1,
"currency_code": "EUR",
"product_cost": 79.99,
"return_reason": "wrong size"
}
],
"to_address": {
"first_name": "Perform",
"last_name": "Warehouse",
"line1": "12 Hafenstrasse",
"postal_code": "10115",
"city": "Berlin",
"country_code": "DE"
},
"from_address": {
"first_name": "Jane",
"last_name": "Doe",
"line1": "52 Bread Street",
"postal_code": "049145",
"city": "Singapore",
"country_code": "SG"
}
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
return_ticket: {
return_id: 'RMA-2026-0042',
comment: 'Size is too small.',
refund_method: 'store_credit',
return_method: 'drop_off'
},
shipment: {
shipment_id: 'SHP-RET-2026-000042',
order_id: 'ORD-2026-000114',
line_items: [
{
product_name: 'Running Shoes',
quantity: 1,
currency_code: 'EUR',
product_cost: 79.99,
return_reason: 'wrong size'
}
],
to_address: {
first_name: 'Perform',
last_name: 'Warehouse',
line1: '12 Hafenstrasse',
postal_code: '10115',
city: 'Berlin',
country_code: 'DE'
},
from_address: {
first_name: 'Jane',
last_name: 'Doe',
line1: '52 Bread Street',
postal_code: '049145',
city: 'Singapore',
country_code: 'SG'
}
}
})
};
fetch('https://api.perform.ai/v5/return/', 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.perform.ai/v5/return/",
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([
'return_ticket' => [
'return_id' => 'RMA-2026-0042',
'comment' => 'Size is too small.',
'refund_method' => 'store_credit',
'return_method' => 'drop_off'
],
'shipment' => [
'shipment_id' => 'SHP-RET-2026-000042',
'order_id' => 'ORD-2026-000114',
'line_items' => [
[
'product_name' => 'Running Shoes',
'quantity' => 1,
'currency_code' => 'EUR',
'product_cost' => 79.99,
'return_reason' => 'wrong size'
]
],
'to_address' => [
'first_name' => 'Perform',
'last_name' => 'Warehouse',
'line1' => '12 Hafenstrasse',
'postal_code' => '10115',
'city' => 'Berlin',
'country_code' => 'DE'
],
'from_address' => [
'first_name' => 'Jane',
'last_name' => 'Doe',
'line1' => '52 Bread Street',
'postal_code' => '049145',
'city' => 'Singapore',
'country_code' => 'SG'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.perform.ai/v5/return/"
payload := strings.NewReader("{\n \"return_ticket\": {\n \"return_id\": \"RMA-2026-0042\",\n \"comment\": \"Size is too small.\",\n \"refund_method\": \"store_credit\",\n \"return_method\": \"drop_off\"\n },\n \"shipment\": {\n \"shipment_id\": \"SHP-RET-2026-000042\",\n \"order_id\": \"ORD-2026-000114\",\n \"line_items\": [\n {\n \"product_name\": \"Running Shoes\",\n \"quantity\": 1,\n \"currency_code\": \"EUR\",\n \"product_cost\": 79.99,\n \"return_reason\": \"wrong size\"\n }\n ],\n \"to_address\": {\n \"first_name\": \"Perform\",\n \"last_name\": \"Warehouse\",\n \"line1\": \"12 Hafenstrasse\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"country_code\": \"DE\"\n },\n \"from_address\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"line1\": \"52 Bread Street\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"country_code\": \"SG\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.perform.ai/v5/return/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"return_ticket\": {\n \"return_id\": \"RMA-2026-0042\",\n \"comment\": \"Size is too small.\",\n \"refund_method\": \"store_credit\",\n \"return_method\": \"drop_off\"\n },\n \"shipment\": {\n \"shipment_id\": \"SHP-RET-2026-000042\",\n \"order_id\": \"ORD-2026-000114\",\n \"line_items\": [\n {\n \"product_name\": \"Running Shoes\",\n \"quantity\": 1,\n \"currency_code\": \"EUR\",\n \"product_cost\": 79.99,\n \"return_reason\": \"wrong size\"\n }\n ],\n \"to_address\": {\n \"first_name\": \"Perform\",\n \"last_name\": \"Warehouse\",\n \"line1\": \"12 Hafenstrasse\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"country_code\": \"DE\"\n },\n \"from_address\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"line1\": \"52 Bread Street\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"country_code\": \"SG\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.perform.ai/v5/return/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"return_ticket\": {\n \"return_id\": \"RMA-2026-0042\",\n \"comment\": \"Size is too small.\",\n \"refund_method\": \"store_credit\",\n \"return_method\": \"drop_off\"\n },\n \"shipment\": {\n \"shipment_id\": \"SHP-RET-2026-000042\",\n \"order_id\": \"ORD-2026-000114\",\n \"line_items\": [\n {\n \"product_name\": \"Running Shoes\",\n \"quantity\": 1,\n \"currency_code\": \"EUR\",\n \"product_cost\": 79.99,\n \"return_reason\": \"wrong size\"\n }\n ],\n \"to_address\": {\n \"first_name\": \"Perform\",\n \"last_name\": \"Warehouse\",\n \"line1\": \"12 Hafenstrasse\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"country_code\": \"DE\"\n },\n \"from_address\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"line1\": \"52 Bread Street\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"country_code\": \"SG\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"api_response": "200",
"data": {
"shipment": {
"shipment_uuid": "0601df6b-c3fe-4836-88b6-b61c2dc86cb2",
"order_uuid": null,
"documents": [],
"created_date": "2026-09-20T10:06:50+00:00"
},
"return_ticket": {
"return_uuid": "8e7254ea-c812-49af-ba0d-6834096e30db",
"return_id": "RMA-2026-0042",
"return_status": "pending",
"requested_date": null,
"created_date": "2026-09-20T10:06:50.263044+00:00",
"updated_date": "2026-09-20T10:06:50.263292+00:00"
}
}
}{
"api_response": "<string>",
"warnings": {},
"data": {}
}{
"api_response": "<string>",
"message": "<string>",
"errors": {}
}{
"api_response": 403,
"message": "Key not authorized"
}{
"api_response": 429,
"message": "Throttled"
}{
"api_response": "500",
"message": "System error"
}Authorizations
Used by every functional endpoint. Generate the token with POST /auth/oauth/token/ and send it as Authorization: Bearer {token}.
Body
application/json
⌘I
Create Return
curl --request POST \
--url https://api.perform.ai/v5/return/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"return_ticket": {
"return_id": "RMA-2026-0042",
"comment": "Size is too small.",
"refund_method": "store_credit",
"return_method": "drop_off"
},
"shipment": {
"shipment_id": "SHP-RET-2026-000042",
"order_id": "ORD-2026-000114",
"line_items": [
{
"product_name": "Running Shoes",
"quantity": 1,
"currency_code": "EUR",
"product_cost": 79.99,
"return_reason": "wrong size"
}
],
"to_address": {
"first_name": "Perform",
"last_name": "Warehouse",
"line1": "12 Hafenstrasse",
"postal_code": "10115",
"city": "Berlin",
"country_code": "DE"
},
"from_address": {
"first_name": "Jane",
"last_name": "Doe",
"line1": "52 Bread Street",
"postal_code": "049145",
"city": "Singapore",
"country_code": "SG"
}
}
}
'import requests
url = "https://api.perform.ai/v5/return/"
payload = {
"return_ticket": {
"return_id": "RMA-2026-0042",
"comment": "Size is too small.",
"refund_method": "store_credit",
"return_method": "drop_off"
},
"shipment": {
"shipment_id": "SHP-RET-2026-000042",
"order_id": "ORD-2026-000114",
"line_items": [
{
"product_name": "Running Shoes",
"quantity": 1,
"currency_code": "EUR",
"product_cost": 79.99,
"return_reason": "wrong size"
}
],
"to_address": {
"first_name": "Perform",
"last_name": "Warehouse",
"line1": "12 Hafenstrasse",
"postal_code": "10115",
"city": "Berlin",
"country_code": "DE"
},
"from_address": {
"first_name": "Jane",
"last_name": "Doe",
"line1": "52 Bread Street",
"postal_code": "049145",
"city": "Singapore",
"country_code": "SG"
}
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
return_ticket: {
return_id: 'RMA-2026-0042',
comment: 'Size is too small.',
refund_method: 'store_credit',
return_method: 'drop_off'
},
shipment: {
shipment_id: 'SHP-RET-2026-000042',
order_id: 'ORD-2026-000114',
line_items: [
{
product_name: 'Running Shoes',
quantity: 1,
currency_code: 'EUR',
product_cost: 79.99,
return_reason: 'wrong size'
}
],
to_address: {
first_name: 'Perform',
last_name: 'Warehouse',
line1: '12 Hafenstrasse',
postal_code: '10115',
city: 'Berlin',
country_code: 'DE'
},
from_address: {
first_name: 'Jane',
last_name: 'Doe',
line1: '52 Bread Street',
postal_code: '049145',
city: 'Singapore',
country_code: 'SG'
}
}
})
};
fetch('https://api.perform.ai/v5/return/', 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.perform.ai/v5/return/",
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([
'return_ticket' => [
'return_id' => 'RMA-2026-0042',
'comment' => 'Size is too small.',
'refund_method' => 'store_credit',
'return_method' => 'drop_off'
],
'shipment' => [
'shipment_id' => 'SHP-RET-2026-000042',
'order_id' => 'ORD-2026-000114',
'line_items' => [
[
'product_name' => 'Running Shoes',
'quantity' => 1,
'currency_code' => 'EUR',
'product_cost' => 79.99,
'return_reason' => 'wrong size'
]
],
'to_address' => [
'first_name' => 'Perform',
'last_name' => 'Warehouse',
'line1' => '12 Hafenstrasse',
'postal_code' => '10115',
'city' => 'Berlin',
'country_code' => 'DE'
],
'from_address' => [
'first_name' => 'Jane',
'last_name' => 'Doe',
'line1' => '52 Bread Street',
'postal_code' => '049145',
'city' => 'Singapore',
'country_code' => 'SG'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.perform.ai/v5/return/"
payload := strings.NewReader("{\n \"return_ticket\": {\n \"return_id\": \"RMA-2026-0042\",\n \"comment\": \"Size is too small.\",\n \"refund_method\": \"store_credit\",\n \"return_method\": \"drop_off\"\n },\n \"shipment\": {\n \"shipment_id\": \"SHP-RET-2026-000042\",\n \"order_id\": \"ORD-2026-000114\",\n \"line_items\": [\n {\n \"product_name\": \"Running Shoes\",\n \"quantity\": 1,\n \"currency_code\": \"EUR\",\n \"product_cost\": 79.99,\n \"return_reason\": \"wrong size\"\n }\n ],\n \"to_address\": {\n \"first_name\": \"Perform\",\n \"last_name\": \"Warehouse\",\n \"line1\": \"12 Hafenstrasse\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"country_code\": \"DE\"\n },\n \"from_address\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"line1\": \"52 Bread Street\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"country_code\": \"SG\"\n }\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.perform.ai/v5/return/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"return_ticket\": {\n \"return_id\": \"RMA-2026-0042\",\n \"comment\": \"Size is too small.\",\n \"refund_method\": \"store_credit\",\n \"return_method\": \"drop_off\"\n },\n \"shipment\": {\n \"shipment_id\": \"SHP-RET-2026-000042\",\n \"order_id\": \"ORD-2026-000114\",\n \"line_items\": [\n {\n \"product_name\": \"Running Shoes\",\n \"quantity\": 1,\n \"currency_code\": \"EUR\",\n \"product_cost\": 79.99,\n \"return_reason\": \"wrong size\"\n }\n ],\n \"to_address\": {\n \"first_name\": \"Perform\",\n \"last_name\": \"Warehouse\",\n \"line1\": \"12 Hafenstrasse\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"country_code\": \"DE\"\n },\n \"from_address\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"line1\": \"52 Bread Street\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"country_code\": \"SG\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.perform.ai/v5/return/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"return_ticket\": {\n \"return_id\": \"RMA-2026-0042\",\n \"comment\": \"Size is too small.\",\n \"refund_method\": \"store_credit\",\n \"return_method\": \"drop_off\"\n },\n \"shipment\": {\n \"shipment_id\": \"SHP-RET-2026-000042\",\n \"order_id\": \"ORD-2026-000114\",\n \"line_items\": [\n {\n \"product_name\": \"Running Shoes\",\n \"quantity\": 1,\n \"currency_code\": \"EUR\",\n \"product_cost\": 79.99,\n \"return_reason\": \"wrong size\"\n }\n ],\n \"to_address\": {\n \"first_name\": \"Perform\",\n \"last_name\": \"Warehouse\",\n \"line1\": \"12 Hafenstrasse\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"country_code\": \"DE\"\n },\n \"from_address\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"line1\": \"52 Bread Street\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"country_code\": \"SG\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"api_response": "200",
"data": {
"shipment": {
"shipment_uuid": "0601df6b-c3fe-4836-88b6-b61c2dc86cb2",
"order_uuid": null,
"documents": [],
"created_date": "2026-09-20T10:06:50+00:00"
},
"return_ticket": {
"return_uuid": "8e7254ea-c812-49af-ba0d-6834096e30db",
"return_id": "RMA-2026-0042",
"return_status": "pending",
"requested_date": null,
"created_date": "2026-09-20T10:06:50.263044+00:00",
"updated_date": "2026-09-20T10:06:50.263292+00:00"
}
}
}{
"api_response": "<string>",
"warnings": {},
"data": {}
}{
"api_response": "<string>",
"message": "<string>",
"errors": {}
}{
"api_response": 403,
"message": "Key not authorized"
}{
"api_response": 429,
"message": "Throttled"
}{
"api_response": "500",
"message": "System error"
}