Returns

Returns in Ecart API represent the reverse flow of commerce: the customer sends items back to the seller. While Orders capture the forward flow (customer buys → seller ships → customer receives), Returns capture the backward flow (customer requests return → seller approves or rejects → customer ships back → seller receives).

Returns are more complex than forward fulfillment: they involve the return request (which items, why), approval or rejection, reverse logistics (who pays for shipping, where items go), and financial consequences (refund, exchange, store credit). Not every ecommerce platform exposes a structured returns API—some handle it only in their UI, some expose a partial API, and some offer a full programmatic flow. Ecart API normalizes returns into three sub-resources:

Concept	Meaning
Return	The return request: which items the customer wants to return, why, and current status (requested, approved, rejected, cancelled).
Return Fulfillment	The reverse shipment: tracking for the package the customer sends back.
Return Package	The package in the return context, with identifiers and status consistent with the forward-flow Package model.

Important: Returns support varies significantly across platforms. Some have a full returns flow; some marketplaces handle returns internally and expose limited or read-only data; others do not expose returns via API. Check whether the platform supports the operations you need before building a returns workflow.

API endpoints

Return (the return request)

Method	Path	Description
GET	`/api/v2/returns`	List returns not tied to a specific order. Some platforms expose returns as a top-level resource.
GET	`/api/v2/orders/{orderId}/returns`	List returns for a specific order. Most common way to access returns.
GET	`/api/v2/orders/{orderId}/returns/{id}`	Get a single return by id.
POST	`/api/v2/orders/{orderId}/returns`	Create a return request for an order.
POST	`/api/v2/orders/{orderId}/returns/{id}/cancel`	Cancel a return request.
POST	`/api/v2/orders/{orderId}/returns/{id}/approve`	Approve a return request.
POST	`/api/v2/orders/{orderId}/returns/{id}/reject`	Reject a return request.

Return Fulfillment (reverse shipment)

Method	Path	Description
GET	`/api/v2/orders/{orderId}/returns/{returnId}/fulfillments`	List fulfillments (reverse shipments) for a return.
GET	`/api/v2/orders/{orderId}/returns/{returnId}/fulfillments/{id}`	Get a single return fulfillment.
POST	`/api/v2/orders/{orderId}/returns/{returnId}/fulfillments`	Create a return fulfillment (provide tracking for the send-back).

Approve, reject, and cancel are platform-dependent. Some platforms auto-approve; others require manual approval. The API returns an error if the action is not supported.

Return — main response fields

Field	Description
`returnOrderId`	The return's unique id on the platform. Use it for subsequent calls (approve, reject, get fulfillments).
`returnFulfillmentOrderId`	Reverse fulfillment order id—similar concept to fulfillmentOrderId on the forward flow. Needed when creating a return fulfillment on some platforms.
`status`	Current status (e.g. requested, approved, rejected, closed, cancelled). Values depend on the platform.
`returnItems`	Items being returned: `returnItemId`, `quantity`, `returnReason` (e.g. damaged, wrong_item, not_as_described).
`items`	Extended item details when available: link between return and original order line items.

Return Fulfillment and Return Package

A Return Fulfillment is the reverse delivery: the actual shipment of items from the customer back to the seller. It includes tracking (number, company, url), optional document (e.g. return label), and status. Return Package is the "reverse package" in the return context, with returnFulfillmentOrderId and status—conceptually the mirror of a forward Package.

When creating a return fulfillment, the payload is under the key returnFulfillment and can include tracking, items, package, documents, and other logistics fields. Structure is similar to a regular Fulfillment but for the send-back shipment.

Key takeaways

Point	Description
Reverse flow	Order → Package → Fulfillment becomes Return → Return Package → Return Fulfillment.
returnFulfillmentOrderId	Reverse-flow equivalent of fulfillmentOrderId; identifies the "reverse package" for the return.
Platform support	Verify that the target platform supports the operations you need (create, approve, reject, return fulfillments).

For request payloads, query filters, and per-platform behaviour, see the API Reference (returns).