Request a New Return (In-Band Error Response)

post

https://api.talkdeskapp.com/erc/ecommerce/order/request-return

Request a new return for an order.

Required fields:

order_id
return_line_items

Unlike the standard create-return endpoint, this endpoint always returns
HTTP 200. Provider-level errors (validation failures, order not found,
bad gateway, etc.) are surfaced via error_code/error_message fields
in the response body instead of HTTP 4xx/5xx status codes. Check
error_code to determine the outcome.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Scope

erc-ecommerce-return:write

Body Params

Request Return Request.

The request return request body.

order_id

string

required

length between 1 and 255

The order ID.

brand

string

length between 1 and 255

Optional brand identifier for the request return operation. If the account is multi-brand, this parameter is required.

return_line_items

array of objects

required

length ≥ 1

The line items to be returned.

return_line_items*

line_item_id

string

required

length between 1 and 255

The ID of the item from the Get Order Items API.

delivery_id

string

length between 1 and 255

The ID of the order delivery from the Get Order Items API.

quantity

integer

required

1 to 100000

Defaults to 1

The quantity to return, which must be positive.

restocking_percentage

integer

1 to 99

The restocking fee percentage, which must be between 1 and 99.

reason

string

required

The reason type for the return item from the Get Return Reasons API.

reason_note

string

length ≤ 255

The additional notes for the return reason.

exchange_line_items

array of objects

The line items to be exchanged. For Shopify stores the exchange items are recorded on the return and only become order items once the return is processed. When the store uses AfterShip for returns, the exchange items are ignored and the return is created without them.

exchange_line_items

return_shipping_fee

number

> 0

The return shipping fee.

return_method

string

The return method for the return.

Responses

Language

Credentials

OAuth2

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Scope

200The request return response. Always returns HTTP 200 for both success and provider-level errors (validation failures, order not found, bad gateway, etc.). Check error_code to determine the outcome.

401Unauthorized

403Forbidden

405Method not supported

500Internal Server Error