> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Return

> Create a Return Ticket and its Return Shipment via the API.

`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](/api-reference/v5/returns/create-return).

<Info>
  The Returns APIs are available to accounts using the **Perform.AI Returns Experience**. Contact your account team to enable it.
</Info>

## 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.

<Note>
  Returning with a **preprinted label** that shipped inside the outbound box? Use the [preprinted-label variant](/guides/create-return-preprinted-label) — same endpoint, different request shape.
</Note>

## The request

Two required objects:

```bash theme={null}
curl --request POST \
  --url https://api.perform.ai/v5/return/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "return_ticket": {
      "return_id": "RMA-2026-0042",
      "comment": "Size is too small.",
      "refund_method": "store_credit",
      "return_method": "drop_off"
    },
    "shipment": {
      "shipment_id": "SHP-RET-2026-000042",
      "order_id": "ORD-2026-000114",
      "line_items": [
        { "product_name": "Running Shoes", "quantity": 1, "currency_code": "EUR", "product_cost": 79.99, "return_reason": "wrong size" }
      ],
      "to_address": { "first_name": "Perform", "last_name": "Warehouse", "line1": "12 Hafenstrasse", "postal_code": "10115", "city": "Berlin", "country_code": "DE" },
      "from_address": { "first_name": "Jane", "last_name": "Doe", "line1": "52 Bread Street", "postal_code": "049145", "city": "Singapore", "country_code": "SG" }
    }
  }'
```

**`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](/guides/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.

<Warning>
  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.
</Warning>

## The response

```json theme={null}
{
  "api_response": "200",
  "data": {
    "shipment": {
      "shipment_uuid": "0601df6b-c3fe-4836-88b6-b61c2dc86cb2",
      "order_uuid": null,
      "documents": [],
      "created_date": "2026-09-20T10:06:50+00:00"
    },
    "return_ticket": {
      "return_uuid": "8e7254ea-c812-49af-ba0d-6834096e30db",
      "return_id": "RMA-2026-0042",
      "return_status": "pending",
      "requested_date": null,
      "created_date": "2026-09-20T10:06:50.263044+00:00",
      "updated_date": "2026-09-20T10:06:50.263292+00:00"
    }
  }
}
```

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](/guides/retrieve-shipment).

<Tip>
  Identical create requests are deduplicated for **30 minutes** — a retry after a timeout returns the original response instead of creating a duplicate Return.
</Tip>

## Next steps

* [Update the Return](/guides/update-return) — approve, reject, or amend it.
* Track return progress with [Retrieve Shipment Details v5.2](/guides/retrieve-shipment), which includes the `returns` object.