Create a Return with a preprinted label

Some merchants ship a preprinted return label inside the outbound parcel. When the consumer uses it, no label needs generating — you just register the Return Shipment so Perform.AI can track it. This is the same POST /v5/return/ endpoint as Create a Return, with a different request shape. Full specs: API reference.

The Returns APIs are available to accounts using the Perform.AI Returns Experience. Contact your account team to enable it.

The preprinted-label flow additionally requires the Preprinted Return Labels setting on your account — contact your account team.

The request: shipment only

Send only the shipment object — no return_ticket:

curl --request POST \
  --url https://api.perform.ai/v5/return/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "shipment": {
      "shipment_id": "SHP-RET-2026-000043",
      "tracking_number": "00340434616780000099",
      "carrier_reference": "dhl-ecommerce-de",
      "order_id": "ORD-2026-000114",
      "to_address": { "first_name": "Perform", "last_name": "Warehouse", "line1": "12 Hafenstrasse", "postal_code": "10115", "city": "Berlin", "country_code": "DE" }
    }
  }'

Field rules for this flow:

Field	Requirement
`shipment_id`	Required.
`tracking_number` + `carrier_reference`	Required if you are not using Perform.AI Booking — the preprinted label’s tracking number and its carrier, so tracking works from the moment the consumer ships.
`order_id`	Highly recommended — links the return to the outbound order.
Addresses	`recipient`, `sender`, `to`, `from` — no `return_address` in this flow.

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 is the nested data.shipment + data.return_ticket shape described in Create a Return.

Updating later

Use the preprinted-label update variant — identification works by shipment_id/shipment_uuid in this flow.

Get Started

Core Concepts

API Essentials

Shipments

Booking & Labels

Returns

Events

Webhooks

Checkout

Customer Experience

Integrations

Resources

Create a Return with a preprinted label

The request: shipment only

Updating later

​The request: shipment only

​Updating later

The request: shipment only

Updating later