Skip to main content
POST /v5/return/ creates a Return — a Return Ticket (the return request’s data) plus a Return Shipment (the parcel traveling back to you). Full field specs: API reference.
The Returns APIs are available to accounts using the Perform.AI Returns Experience. Contact your account team to enable it.

​
When to use this API

Use it when the return request happens outside the branded returns widget — in your own returns portal, customer-service tooling, or marketplace flow. The widget creates returns itself and copies order, address, and line-item data from the outbound Shipment; via the API, you provide that data.
Returning with a preprinted label that shipped inside the outbound box? Use the preprinted-label variant — same endpoint, different request shape.

​
The request

Two required objects:
return_ticket — all fields optional: return_id (your RMA reference — unique in the account, immutable after creation), refund_method (original_payment / store_credit / exchange), return_method (drop_off / pick_up / send_by_consumer / return_to_store), comment, return_proofs (consumer proof images: url + file_name), requested_date, cost_of_return, additional_cost, reject_reason, approver_email, internal_notes. shipment — takes the same fields as Create Shipment, with return-specific rules:
  • shipment_id is required, and the Return needs at least one line item — the item being returned (return_reason on the line item is worth filling).
  • Don’t send tracking_number or carrier_reference — the Return Booking Service assigns them when the return label is generated.
  • order_id is highly recommended: it links the Return to the outbound order.
Only the notification_email / notification_phone arrays subscribe recipients to tracking notifications. The email and phone inside address objects are contact data — they never receive notifications.

​
The response

Note the shape: unlike Create Shipment’s flat data, returns nest shipment and return_ticket. New Returns start in return_status: "pending"; the full status lifecycle is visible via Retrieve Shipment Details v5.2.
Identical create requests are deduplicated for 30 minutes — a retry after a timeout returns the original response instead of creating a duplicate Return.

​
Next steps