Return request API

Create return request API

Create a return request after an order succeeds.

Request Headers

X-Signature - requiredstring

A signature is a string used to verify data integrity between your system and SimplifyTrip. Use checksumKey from API Key and HMAC_SHA256 to generate signature on alphabetically sorted data format. See Verify data with signature.

Request Body

trackId - required

string

ID generated by your system to identify the return request. When receiving webhook data, trackId helps map to the correct request.

orderId - required

string SimplifyTrip orderId received after successful order creation.

reason

string Return reason (optional)

returnType - required

FULL | PARTIAL

Return the whole order or partial items. For full-order return, items is not required.

items

Item[] List of items you want to return from the order

`sku` - required	`string` Product SKU in your order
`quantity` - required	`number` Return quantity (must be less than or equal to purchased quantity)

Responses

200 OK

application/json

Success

id

string Return request ID

orderId

string Purchased order ID

trackId

string ID provided by your system

createdAt datetime

reason

string Return reason

status REQUESTED

returnType FULL | PARTIAL

refundAmount

number Amount refunded when return succeeds

items Item[]

`productName`	`string`
`sku`	`string`
`quantity`	`number`
`type`	`eSIM \| SIM`

4xx/5xx Error

application/json

Error

`timestamp`	`timestamp`
`statusCode`	`number`
`errorCode`	`string`
`message`	`string`

POST

/api/v1/return-requests

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_61// Using axios
_61import axios from 'axios';
_61
_61const options = {
_61	method: 'POST',
_61	url: 'https://merchant.simplifytrip.com/api/v1/return-requests',
_61	headers: {
_61		accept: 'application/json',
_61		'content-type': 'application/json',
_61		authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxxxx',
_61		'x-api-key': 'pk_live_xxxxxxxxxxxxxxxxxx',
_61		'x-signature': '412e915d2871504ed31be63c8f62a149a4410d34c4c42affc9006ef9917eaa03',
_61	}
_61	data: {
_61		'trackId': 'b4b08205-836e-4296-a054-52462089edf6',
_61		"orderId": "52462089edf6",
_61		"returnType": "PARTIAL",
_61		"reason": "",
_61		'items': [
_61			{
_61				'sku': 'E23XY06GB08DFX',
_61				'quantity': 2
_61			}
_61		]
_61	}
_61};
_61
_61axios
_61	.request(options)
_61	.then(res => console.log(res.data))
_61	.catch(err => console.error(err));
_61
_61// Using fetch api
_61const url = 'https://merchant.simplifytrip.com/api/v1/return-requests';
_61const options = {
_61	method: 'POST',
_61	headers: {
_61		accept: 'application/json',
_61		'content-type': 'application/json',
_61		authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxxxx',
_61		'x-api-key': 'pk_live_xxxxxxxxxxxxxxxxxx',
_61		'x-signature': '412e915d2871504ed31be63c8f62a149a4410d34c4c42affc9006ef9917eaa03',
_61	}
_61	body: JSON.stringify({
_61		"trackId": "b4b08205-836e-4296-a054-52462089edf6",
_61		"orderId": "52462089edf6",
_61		"returnType": "PARTIAL",
_61		"reason": "",
_61		"items": [
_61			{
_61				"sku": "E23XY06GB08DFX",
_61				"quantity": 2
_61			}
_61		]
_61	}),
_61};
_61
_61fetch(url, options)
_61	.then(res => res.json())
_61	.then(json => console.log(json))
_61	.catch(err => console.error(err));

Sample Response

Success

Error


_18{
_18  "id": "52462089edf6",
_18  "createdAt": "2025-12-01 09:25:03",
_18  "reason": "",
_18  "status": "REQUESTED",
_18  "returnType": "PARTIAL",
_18  "refundAmount": 100000,
_18  "orderId": "658441501843542",
_18  "trackId": "b4b08205-836e-4296-a054-52462089edf6",
_18  "items": [
_18    {
_18      "productName": "Southeast Asia SIM (7 countries), data-only (Unlimited Data/day - 3 days)",
_18      "sku": "AS7BCUNL03DPY",
_18      "quantity": 2,
_18	  "type": "SIM"
_18	}
_18  ]
_18}

Cancel refund request API

Cancel a refund request by the provided ID.

Request Headers

X-Signature - requiredstring

Request Body

returnId - required

string Return request ID to cancel

Responses

200 OK

application/json

Success

id

string

Return request ID generated by SimplifyTrip

trackId

string

System-generated ID

createdAt datetime

returnType FULL | PARTIAL

status CANCELED

reason string

refundAmount number

items Item[]

`productName`	`string`
`sku`	`string`
`quantity`	`number`
`type`	`eSIM \| SIM` Product type

4xx/5xx Error

application/json

Error

`timestamp`	`timestamp`
`statusCode`	`number`
`errorCode`	`string`
`message`	`string`

POST

/api/v1/return-requests/cancel

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_41// Using axios
_41import axios from 'axios';
_41
_41const options = {
_41	method: 'POST',
_41	url: 'https://merchant.simplifytrip.com/api/v1/return-requests/cancel',
_41	headers: {
_41		accept: 'application/json',
_41		'content-type': 'application/json',
_41		authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxxxx',
_41		'x-api-key': 'pk_live_xxxxxxxxxxxxxxxxxx',
_41	},
_41	data: {
_41		'returnId': '52462089edf6'
_41	}
_41};
_41
_41axios
_41	.request(options)
_41	.then(res => console.log(res.data))
_41	.catch(err => console.error(err));
_41
_41// Using fetch api
_41const url = 'https://merchant.simplifytrip.com/api/v1/return-requests/cancel';
_41const options = {
_41	method: 'POST',
_41	headers: {
_41		accept: 'application/json',
_41		'content-type': 'application/json',
_41		authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxxxx',
_41		'x-api-key': 'pk_live_xxxxxxxxxxxxxxxxxx',
_41	},
_41	body: JSON.stringify({
_41		"returnId": "52462089edf6"
_41	}),
_41};
_41
_41fetch(url, options)
_41	.then(res => res.json())
_41	.then(json => console.log(json))
_41.catch(err => console.error(err));

Sample Response

Success

Error


_17{
_17  "id": "6740ce7f9d04259159bc6401",
_17  "trackId": "b4b08205-836e-4296-a054-52462089edf6",
_17  "createdAt": "2024-11-22T18:33:35.127Z",
_17  "status": "CANCELED",
_17  "returnType": "PARTIAL",
_17  "refundAmount": 840000,
_17  "reason": null,
_17  "items": [
_17    {
_17      "productName": "Southeast Asia SIM (7 countries), data-only (Unlimited Data/day - 3 days)",
_17      "quantity": 2,
_17      "sku": "E23XY06GB08DFX",
_17      "type": "eSIM"
_17    }
_17  ]
_17}

Get refund request details API

Returns detailed information of a refund request by the provided ID.

Path Parameters

id - required

string

Return request ID or trackId to query. Ensure trackId is unique.

Responses

200 OK

application/json

Success

id

string

Return request ID generated by SimplifyTrip

trackId

string

System-generated ID

createdAt datetime

returnType FULL | PARTIAL

status

REQUESTED | REVIEWING | APPROVED | REJECTED | CANCELED Return request status

reason string

refundAmount number

items Item[]

`productName`	`string`
`sku`	`string`
`quantity`	`number`
`type`	`eSIM \| SIM` Product type

4xx/5xx Error

application/json

Error

`timestamp`	`timestamp`
`statusCode`	`number`
`errorCode`	`string`
`message`	`string`

GET

/api/v1/return-requests/:id

Sample Request

Try it on Swagger

Nodejs

PHP

Java

Curl


_35// Using axios
_35import axios from 'axios';
_35
_35const options = {
_35	method: 'GET',
_35	url: 'https://merchant.simplifytrip.com/api/v1/return-requests/658441501843542',
_35	headers: {
_35		accept: 'application/json',
_35		'content-type': 'application/json',
_35		authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxxxx',
_35		'x-api-key': 'pk_live_xxxxxxxxxxxxxxxxxx',
_35	}
_35};
_35
_35axios
_35	.request(options)
_35	.then(res => console.log(res.data))
_35	.catch(err => console.error(err));
_35
_35// Using fetch api
_35const url = 'https://merchant.simplifytrip.com/api/v1/return-requests/658441501843542';
_35const options = {
_35	method: 'GET',
_35	headers: {
_35		accept: 'application/json',
_35		'content-type': 'application/json',
_35		authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxxxx',
_35		'x-api-key': 'pk_live_xxxxxxxxxxxxxxxxxx',
_35	}
_35};
_35
_35fetch(url, options)
_35	.then(res => res.json())
_35	.then(json => console.log(json))
_35.catch(err => console.error(err));

Sample Response

Success

Error


_17{
_17  "id": "6740ce7f9d04259159bc6401",
_17  "trackId": "b4b08205-836e-4296-a054-52462089edf6",
_17  "createdAt": "2024-11-22T18:33:35.127Z",
_17  "status": "REQUESTED",
_17  "returnType": "PARTIAL",
_17  "refundAmount": 840000,
_17  "reason": null,
_17  "items": [
_17    {
_17      "productName": "Southeast Asia SIM (7 countries), data-only (Unlimited Data/day - 3 days)",
_17      "quantity": 2,
_17      "sku": "E23XY06GB08DFX",
_17      "type": "eSIM"
_17    }
_17  ]
_17}

Order Errors