Returns Experience: Manage Consumer Returns via API

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.

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

{
  "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"
  }
}

Get Started

Core Concepts

API Essentials

Shipments

Booking & Labels

Returns

Events

Webhooks

Checkout

Customer Experience

Integrations

Resources

Returns Experience: Manage Consumer Returns via API

Two Core Data Objects

1. Return Ticket

2. Return Shipment

Return Methods

Refund Methods

Return Statuses

When to Use the API vs. the Widget

​Two Core Data Objects

​1. Return Ticket

​2. Return Shipment

​Return Methods

​Refund Methods

​Return Statuses

​When to Use the API vs. the Widget

Two Core Data Objects

1. Return Ticket

2. Return Shipment

Return Methods

Refund Methods

Return Statuses

When to Use the API vs. the Widget