Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Prefix the value with "ApiKey" to indicate the custom authorization type

Body

application/json

Request to create a return order

personId
string<uuid>
required

ID of the person the return is for

Example:

"123e4567-e89b-12d3-a456-426614174000"

returnItems
object[]
required

Items to include in the return

Minimum array length: 1
requestAddressConfirmation
boolean
required

Whether to request address confirmation from the person before shipping the return kit

returnKitAddress
object

Address for the return kit shipment. Required when requestAddressConfirmation is false (the default). Omit only when requestAddressConfirmation is true, in which case the person is prompted to confirm their address before the kit ships.

officeId
string<uuid>

Office ID to return equipment to. When provided, returnTo is set to OFFICE and returnMethod is forced to SHIPMENT

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Return order created

id
string<uuid>
required

Return order ID

Example:

"ed92d1a0-a8ee-4768-bbcb-26dd4bfdf8a4"

retrievals
object[]
required

Retrieval methods grouped by type. Always contains 4 entries: PL, RETURN_KIT, INBOUND, NOT_MAPPED

personId
string<uuid> | null

Person ID

Example:

"016fb454-066b-4ba5-9eca-a2fa14b7e7fc"

supportTicketId
integer<int64>

Support ticket ID

Example:

12345

createdAt
string<date>

Created date

Example:

"2025-11-26"

updatedAt
string<date>

Updated date

Example:

"2025-11-26"

confirmedAtTimestamp
string<date-time>

Confirmed timestamp (UTC)

Example:

"2025-11-27T10:15:00Z"

shippingAddress
object

Shipping address

status
enum<string>

Return order status

Available options:
PENDING,
PROCESSING,
COMPLETED,
RETURN_KIT_SENT,
RETURN_KIT_DELIVERED,
RETURN_KIT_SENT_BACK,
RECEIVED_IN_WAREHOUSE,
RETURNED,
NOT_RETURNED,
SUBMITTED,
CANCELLED,
NONE,
CONFIRMED,
PARTIALLY_COMPLETED,
NOT_COMPLETED
Example:

"CONFIRMED"

replacement
object

Replacement order if applicable

returnLifecycleType
enum<string>

Return lifecycle type

Available options:
ONE_OFF,
OFFBOARDING
Example:

"ONE_OFF"

submittedBy
null

Person who submitted the return order.

office
null

Office associated with the return, if any.

person
null

Affected person reference (sibling to legacy personId).

deliveryLocation
enum<string> | null

The return's delivery location (mirrors the FE Returns 'Delivery location' column). Allowed values: FIRSTBASE, OFFICE, MULTIPLE.

Available options:
FIRSTBASE,
OFFICE,
MULTIPLE
personLastDay
string<date> | null
read-only

Last Day of the person associated with this return, in ISO 8601 date format. Omitted when the person has no Last Day.

Example:

"2026-01-31"