Create Returns and Return Labels

Use the /v1/shipos/returns endpoints with an API key in x-access-token, or the same operations through Cybership MCP. Creation and label purchase require WRITE_RETURNS; retrieval and rate shopping require READ_RETURNS. The returns feature must be enabled for the team.

Create a return

Choose one operation:

• POST /v1/shipos/returns/from-order accepts warehouse_id, order_id, and line_items with core_order_line_item_id, quantity_to_return, and return_reason.
• POST /v1/shipos/returns/standalone accepts warehouse_id, return_type, customer contact and address fields, and line_items with a product ID or name, quantity, and return reason. A fulfiller may specify a delegated merchant_team_id.

The response includes the return id, RMA number, status, and line items. Creation starts at AWAITING_LABEL and does not purchase postage. Persist the return ID before requesting a label. A caller must own the warehouse or be the merchant using an authorized fulfillment delegation. Order, merchant, product, and warehouse relationships are checked independently.

Select and purchase a label

1. Call GET /v1/shipos/returns/{return_id}/label/rates.
2. Choose a returned rate. Pass its carrier_integration_id, carrier_id, service_id, and, when present, provider_rate_id to POST /v1/shipos/returns/{return_id}/label.
3. Alternatively, send {} to select the cheapest available rate.
4. Call GET /v1/shipos/returns/{return_id} to retrieve its status, tracking information, and label_url.

The label response includes the label ID, carrier, service, tracking number, download URL, cost, and currency. The existing return workflow handles packing slips, webhooks, billing, and optional customer email (send_customer_email). Carrier and service availability follow the existing integration's return-label support.

Retries and errors

These endpoints use the existing return workflow. Creation does not accept an idempotency key: repeating a creation request can create another return. Do not automatically retry creation after a timeout without first confirming whether the return was created.

Label generation reuses a label already linked to the package. This does not guarantee duplicate-purchase protection when a carrier purchase times out before its result is saved. Check the return and confirm the carrier outcome before retrying an ambiguous purchase. A missing label URL is not proof that postage was not purchased.

Validation, permission, and provider errors are returned through the public API's standard error response. Rate-shopping errors are returned alongside any successful rates. Refresh rates after a quote expires or is rejected.

MCP

Search for “return” with search_cybership_operations, inspect the selected operation with describe_cybership_operation, and invoke it with execute_cybership_operation. Use the same operation paths without the /v1 prefix in operation_key; pass the return ID in path_parameters. Writes require confirm_write: true. Keep the returned IDs for subsequent tool calls; follow the retry guidance above.

The MCP catalog is maintained in this repository from the public OpenAPI artifact; no external client regeneration is required for Cybership MCP. The repository command is pnpm --filter @cybership/server generate:public-api, followed by pnpm --filter @cybership/server mcp:check. It updates apps/server/src/api/public/generated/routes.ts, swagger.json, and apps/server/src/mcp/generated/catalog-manifest.json. Independently generated API clients must be regenerated from that swagger.json using their own client generator.