Create or cancel a return order on a Sales Order

POST

/v1/salesOrder/{orderNumber}/returnOrder

curl --request POST \
  --url https://api.zentail.com/v1/salesOrder/1/returnOrder \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "channelReturnId": "example", "requestTs": {}, "cancelled": true, "returnItems": [ { "lineItemId": "example", "quantity": 1, "refundReason": "example" } ] }'

Creates a return order for a return the buyer requested on the sales channel, keyed on channelReturnId. A re-send of the same return changes nothing. Send cancelled: true once the channel cancels or rejects the return; it cancels the return order unless the seller has already completed or cancelled it in Zentail. Every lineItemId is checked first, so one unknown line rejects the whole request with a 400 and writes nothing.

Authorizations

• zentail_oauth
  sales:orders:self

Parameters

Path Parameters

orderNumber

required

number

Zentail Order Number

Request Body

Place all of the return details in a JSON object in the body of the request.

Media typeapplication/json

object

channelReturnId

required

The unique identifier for the return in the sales channel. A re-send with the same value changes nothing.

string

requestTs

The time the buyer requested the return. In ISO-8601 format. Defaults to now.

string format: date-time

default: [object Object]

cancelled

Send true once the channel cancels or rejects the return. It cancels an open return order. A return order the seller already completed or cancelled is left as it is.

boolean

returnItems

The line items being returned. Required to create a return order, and ignored once it exists.

Array<object>

object

lineItemId

required

The channel’s identifier for the line item, as sent in lineItemId when the sales order was created.

string

quantity

required

The quantity being returned.

integer

refundReason

Why the buyer is returning the item.

string

Responses

200

Success

Media typeapplication/json

object

returnOrderId

The unqiue identifier for the return order in Zentail

number

channelReturnId

The unqiue identifier for the return order in the sales channel

string

requestTs

The time that the return order was requested. In ISO-8601 format

string format: date-time

cancelled

Indicates the return request has been cancelled

boolean

completedTs

The time the seller completed the return in Zentail, or null while it is still open. In ISO-8601 format

string format: date-time

returnItems

The line items that makeup the return order

Array<object>

object

returnOrderItemId

The unique identifier for this line item

number

SKU

The SKU that is being returned

string

quantity

The amount that is being returned

number

originalQuantity

The original quantity that was ordered

number

refundAmount

The amount of payment that is being refunded

number

Example^generated

{
  "returnOrderId": 1,
  "channelReturnId": "example",
  "requestTs": "2026-04-15T12:00:00Z",
  "cancelled": true,
  "completedTs": "2026-04-15T12:00:00Z",
  "returnItems": [
    {
      "returnOrderItemId": 1,
      "SKU": "example",
      "quantity": 1,
      "originalQuantity": 1,
      "refundAmount": 1
    }
  ]
}

400

Bad Request

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 400
}

403

Permission Denied

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 403
}

404

Not Found

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 404
}

500

Zentail Error

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

errorMessage

string

Example

{
  "errorCode": 500
}

503

Zentail Error

Media typeapplication/json

object

errorCode

number

errorMessages

Array<string>

referenceId

string format: uuid

Example

{
  "errorCode": 503
}