List your org's returns, as a page

GET /v1/commerce/return/

A return is an RMA — the store, user and order it belongs to, the line items coming back, a fulfillment block carrying its own type, status and pricing, a summary, and eight lifecycle timestamps from submitted through delivered and processed. Its status is a FREE STRING with no enumeration behind it, and there is no refund amount on the return itself: the money sits inside the line items and the fulfillment pricing. Answers a pagination envelope — the page and display echoed back, the rows under models, a total count and a facets array — read from the caller org's own namespaced store, so one tenant can never list another's. Sorting defaults to the last-updated time and is overridable with sort. display is the page size and page applies only alongside it; either one that is not a positive integer is refused with 500 rather than silently ignored, and the limit query overrides the reported COUNT only, never the rows returned. No search backend is wired, so the datastore is the one and only list path and facets is always empty. A request resolving no org namespace is served an EMPTY page rather than an unscoped scan: the namespace IS the tenant filter, so without one there is nothing safe to return. Any valid access token reaches it. The token must also carry Admin or the Return list scope.

Request

GET /v1/commerce/return/ takes no parameters and no body — the credential is the whole request.

Response

The document declares no response body for this operation. It answers 200 on success and the platform error shape on failure — see Errors.

Examples

hanzo commerce return list

import { Configuration, CommerceApi } from 'hanzoai';

const api = new CommerceApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getCommerceReturn();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import CommerceApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = CommerceApi(client).get_commerce_return()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.CommerceAPI.GetCommerceReturn(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, commerce_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = commerce_api::get_commerce_return(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.CommerceApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new CommerceApi(client).getCommerceReturn();

curl https://api.hanzo.ai/v1/commerce/return/ \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "commerce",
         "arguments": {
           "op": "get_commerce_return",
           "input": {}
         }
       }
     }'

Commerce API · All Hanzo APIs · Interactive reference