> ## 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.
# Returns Experience: Manage Consumer Returns via API
> Perform.AI Returns Experience lets you manage consumer return requests and return shipments via API, with full visibility in the Perform.AI portal.
Perform.AI Returns Experience lets you manage consumer return requests and their associated return shipments via API. When a customer initiates a return, Perform.AI creates two linked objects — a **Return Ticket** that captures the return request details and a **Return Shipment** that tracks the physical movement of the parcel back to you.
The Returns Experience feature must be **enabled for your account** before you can use the Returns APIs. Contact your Key Account Manager or Customer Success team to activate it.
## Two Core Data Objects
### 1. Return Ticket
The Return Ticket represents the consumer-initiated return request. It captures what the customer wants to return, why, and how they expect to be refunded.
| Field | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `return_id` | Your user-defined identifier for the return (e.g. an RMA number). Unique across your account. Cannot be changed once set. |
| `return_uuid` | Perform.AI-generated UUID for the return. Use this in update requests. |
| `return_status` | System-generated status across the return lifecycle: `pending approval`, `approved`, `rejected`, `carrier booking pending`, `shipping`, `completed`, `cancelled`, `inactive`, `archived`. |
| `requested_date` | The date and time the consumer submitted the return request. |
| `return_method` | How the consumer will send the item back (`drop_off`, `pick_up`, `send_by_consumer`, `return_to_store`). |
| `refund_method` | How the consumer will be refunded (`original_payment`, `store_credit`, `exchange`). |
| `total_refund_amount` | The total amount to be refunded if the return is approved (e.g. `USD 25.95`). |
### 2. Return Shipment
The Return Shipment is a virtual representation of the physical parcel travelling back to you. It shares the same data structure as a standard outbound shipment.
Every return must include at least one line item in the `line_items` array, representing the product being returned. Requests without a line item will be rejected.
| Field | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `shipment_id` | Your user-defined identifier for the return shipment. **Required** when creating a return via API. |
| `shipment_uuid` | Perform.AI-generated UUID for the return shipment. |
| `tracking_number` | Carrier tracking number. For returns using Perform.AI's Return Booking Service, this is populated automatically when the shipping label is generated. |
| Carrier info | Carrier details are also populated automatically by the Return Booking Service — do not include `tracking_number` or `carrier_reference` in update requests. |
The Return Shipment also supports the full range of shipment fields: addresses, line items, notifications, shipping costs, documents, and tags.
## Return Methods
When creating a return, specify how the consumer will send back the item using the `return_method` field:
| Value | Description |
| ------------------ | ------------------------------------------------------------------------------------ |
| `drop_off` | Consumer drops off the parcel at a designated location (e.g. carrier depot, locker). |
| `pick_up` | Carrier collects the parcel from the consumer's address. |
| `send_by_consumer` | Consumer arranges and pays for their own return shipping. |
| `return_to_store` | Consumer returns the item in person to a retail location. |
## Refund Methods
Use the `refund_method` field to specify how you will refund the consumer:
| Value | Description |
| ------------------ | ------------------------------------------------- |
| `original_payment` | Refund to the consumer's original payment method. |
| `store_credit` | Issue store credit to the consumer. |
| `exchange` | Exchange the returned item for another product. |
## Return Statuses
Perform.AI sets the `return_status` automatically based on your actions:
| Status | Meaning |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `pending` | The return request has been received and is awaiting review. This is the initial status when a return is created. |
| `approved` | You have approved the return request. |
| `rejected` | You have rejected the return request. Set `reject_reason` to communicate the reason to the consumer. |
## When to Use the API vs. the Widget
Perform.AI provides a **branded returns widget** that you can embed on your website. When a consumer uses the widget to submit a return request, the Return Ticket and Return Shipment are **automatically created** in Perform.AI — you don't need to call the API.
Use the **Create Return API** only when the return request step is handled **outside** the branded widget, for example:
* You have built your own returns portal
* You are ingesting returns from a third-party returns management system
* You are programmatically processing returns from your customer service tooling
```json theme={null}
{
"shipment": {
"shipment_id": "RET-SHIP-001",
"order_id": "ORD-20240101-001",
"notification_email": ["customer@example.com"],
"line_items": [
{
"product_name": "Blue Running Shoes (Size 10)",
"product_id": "SHOE-BLU-10",
"quantity": 1
}
]
},
"return_ticket": {
"return_id": "RMA-001",
"return_method": "drop_off",
"refund_method": "original_payment",
"total_refund_amount": "USD 89.99",
"requested_date": "2024-01-15T10:35:55+08:00"
}
}
```