Partner Returns API

Status

The API is available as a partner-ready beta. It does not mean a third-party product has approved or officially listed Opus. Partners should test against a development store before enabling production traffic.

Merchant authorization

Each merchant opens Opus settings, copies their Partner Returns API endpoint and key, and provides them directly to the partner. Keys are scoped to one store, read-only, and can be rotated by the merchant at any time.

Send the key as Authorization: Bearer YOUR_KEY. Opus also accepts X-Authorization: YOUR_KEY. Never place the key in a URL, browser script, log, or customer-facing page.

List return events

Make a GET request to /api/partners/returns?shop=STORE.myshopify.com. Optional parameters are updated_after (an ISO 8601 timestamp), limit (1 to 100, default 50), andcursor. When pagination.has_more is true, repeat the request with the returned next_cursor.

Results are ordered by update time and then event ID. The current response version is 2026-08-29. Clients should ignore unknown fields so additions remain backward compatible.

Returned fields

Each event contains a merchant-scoped event ID, request number, type, requested and final resolution, status, timestamps, and line items. Line items contain the Shopify order-line, product, and variant IDs, quantity, and structured return reason.

The API intentionally excludes customer names, email addresses, postal addresses, payment data, order totals, free-text customer or merchant notes, and uploaded evidence.

Operational limits

Only non-test requests are returned. Responses use private, no-store caching headers. A key may make up to 600 requests per ten-minute window; a 429 response includes a Retry-After header. A 401 response means the merchant removed the app, supplied the wrong store, or rotated the key.

Integration support

For a sample response, field mapping, or beta test, contact johnson@opusreturns.com. Do not send live API keys or customer data by email.