Newsletter
FFM – Return
  • Home
  • FFM – Return

Introduction

ffm.jpg

Last update :

Toolbox / Tips

This API enables sellers to manage warehouse returns in two main scenarios:

  1. Customer Returns: When a buyer requests to return a parcel (due to defect, mismatch, change of mind, etc.). In that case, the seller submits a return request, receives a return label and instructions, and the buyer sends the product back to the warehouse.

  2. Carrier Returns: When a carrier is unable to deliver a shipment and sends it back to the warehouse (for example, undeliverable address, refusal, transport damage, etc.). In this case, no label is generated; the seller is only informed of the return incident.

In both scenarios, the return is linked to a previous outbound shipment through the outboundShipmentId.

This API complements the Outbound Shipments flow: once a parcel has been shipped, some units may later be returned. This endpoint allows you to manage that part of the lifecycle.

Key Attributes

Field

Description

returnId

Unique identifier of the return

type

Return type: Customer or Carrier

status

Processing status of the return. Possible values: Created, Referencing, Referenced, Accepted, Pending, Completed

reason

Reason provided for the return (e.g., ReferenceError, Damaged, Retraction, TransportDamage, etc.)

recommendedReturnReason

Optional classification returned by the warehouse after inspection

comment

Optional comment provided by the seller or logistics partner

warehouseComment

Comment from the warehouse upon reception

outboundShipmentId

Identifier of the outbound shipment linked to this return

reference

Seller’s order reference associated with the return

orderSellerId

Order reference used by the seller

parcelId

ID of the parcel returned

receiptDate

Date the return was received and processed by the warehouse

createdAt

Creation date of the return

updatedAt

Last update date of the return

lines

List of returned products

hasLabel

Whether a return label is available

labelUrl

Endpoint to retrieve the return label

unexpectedQuantity

Quantity received but not declared in the return (extra items)

Seller Workflow

return.png

In this section, you’ll learn how to manage the following use cases and maintain full control over your return operations:

Create a Customer Return

Prerequisites

  • The outbound shipment must already exist and be referenced via its outboundShipmentId.

  • Only products that have already been shipped or delivered can be returned.

  • The productId and the returned quantity must be valid and not exceed the originally shipped quantity.

  • If a return already exists for the same product and shipment covering the entire quantity, it cannot be duplicated.

This endpoint allows sellers to initiate a return request for one or more products from a previously shipped outbound order.

For customer returns, the return triggers return label generation so the buyer can send the goods back to the warehouse.

For carrier returns (e.g., undeliverable parcels), no seller action is required, these returns are automatically created when the carrier notifies the system. You can retrieve these returns but not create them. Use of carrier oriented return reasons will reject the request.

Endpoint to use

  • Request body example:

{
  "outboundShipmentId": "ad36144a-902c-4953-8d5d-98f423cace36",
  "reference": "20231109145205-43572-FFM",
  "reason": "ReferenceError",
  "comment": "Customer received the wrong product",
  "lines": [
    {
      "productId": "PRODUCT001",
      "quantity": 1,
      "productCondition": "RefurbishedLikeNew"
    }
  ]
}

Important notes

  • Label generation may take up to 15 minutes after request submission for customer returns.

  • Carrier returns are registered automatically, this endpoint cannot be used to create them.

  • HTTP 400 errors will occur if product ID, product condition or quantity is invalid or exceeds the eligible amount.

  • Avoid including sensitive data (e.g., medical or financial details) in the comment field.

Count Returns using Filters

Prerequisites

  • Filters should be used to narrow down the count by criteria such as type, status, reason, date range, etc.

The endpoint returns only the total number of returns that match the specified filters, not the full list of objects.

This endpoint provides the total count of returns matching the applied filters.
It is particularly useful for:

  • Performance reporting (e.g., monthly return rate)

  • UI counters showing return totals.

  • Reconciliation dashboards comparing return trends over time.

Endpoint to use

Important notes

  • All filters are optional, except sellerId in the request header.

  • All filters from the search endpoint are supported, including types, reasons, parcel ID, date ranges, status.

  • Combine multiple filters to perform precise segment analysis (e.g., returns by reason and date range).

  • The endpoint returns a single integer representing the total count.

Retrieve Returns using Filters

Prerequisites

  • Pagination is handled through the limit parameter and a cursor, returned in the Link header.

  • Multiple filters can be combined (e.g., status, reference, types, reasons, date ranges).

  • This endpoint returns a paginated list of returns, ordered by creation date unless another sort order is specified.

This endpoint returns a paginated list of returns. It supports extensive filtering options including type (Customer/Carrier), reason, status, date ranges, outboundShipmentId, and parcel ID.

This endpoint allows you to retrieve a detailed list of returns using a wide range of filters.
It is typically used to:

  • Browse or export historical returns

  • Investigate return statuses or customer return reasons

  • Identify carrier-returned parcels for operational processing

  • Build dashboards showing filtered return lists

Endpoint to use

Important notes

  • Returned items include:

    • hasLabel and labelUrl (if a customer return label is available)

    • original outbound shipment details

    • metadata (reason, type, status, timestamps, parcel info)

  • Only the first page is returned unless the cursor is passed, make sure you implement pagination logic.

Retrieve a Specific Return

Prerequisites

  • You must provide the unique returnId of the return to retrieve.

  • The sellerId header is required to ensure the return belongs to the correct seller context.

This endpoint retrieves the full details of a single return, including:

  • Return metadata (type, status, reason, timestamps)

  • Outbound shipment information

  • Product lines and quantities (expected, receipted, conformity)

  • Label availability and link (if applicable)

  • Warehouse feedback (recommended reason, comments, product state)

  • Parcel identifiers and reverse-logistics information

It is typically used to:

  • Review the status and details of a return

  • Validate warehouse reception and product conformity

  • Investigate customer or carrier return issues

Endpoint to use

Important notes

  • Response includes both seller-provided information (reason, comment) and warehouse-provided feedback (product state, unexpected quantity, warehouse comment).

  • The return type (Customer or Carrier) is returned to provide context about how the return was initiated.

  • Parcel-level metadata (parcelId) is included when available, which helps track the returned parcel in reverse logistics flows.

  • The hasLabel and labelUrl fields indicate whether a customer return label is available for download.

Retrieve Return Label Content (PDF/PNG)

Prerequisites

  • The return must have an associated customer return label (carrier returns do not generate labels).

  • The returnId must correspond to an existing return that is eligible for label retrieval.

  • The sellerId header is required to validate the request context.

This endpoint returns the binary content of the return label (PDF or PNG), typically used for:

  • Allowing customers to download or print the return label

  • Embedding the label in seller or marketplace dashboards

  • Automating return documentation in customer service flows

Endpoint to use

Aucun endpoint trouvé avec l'operationId « get-returns-returnid-label ».

Important notes

  • The format of the returned label is determined by the Accept header:

    • application/pdf → PDF label

    • image/png → PNG label

  • The endpoint returns raw binary content. Frontend apps should implement proper file download, rendering, or print workflows.

  • If a return does not have a label, the response may be:

    • 404 Not Found (no label available yet)

    • An empty body, depending on warehouse state

  • Labels are only generated for seller initiated Customer returns. Carrier returns never include downloadable labels.

FAQ

 What is a return in this context?

A return refers to a product coming back to the warehouse, either:

  • Customer return: the seller initiates a return request on behalf of the buyer.

  • Carrier return: the carrier fails to deliver (e.g. refusal, damage), and the parcel is returned

 Who creates a return?

  • Customer returns are created by the seller via POST /returns

  • Carrier returns are created automatically by the warehouse — you only monitor them

 What do I need to create a return?

You must provide at least:

  • A valid outboundShipmentId

  • A list of products (productId, quantity)

You can only return products that have already been shipped or delivered.

 Can I create a return with partial quantities?

Yes. You can return fewer units than were shipped. The system checks that cumulative returned quantities ≤ total shipped quantity.

 Can I create a return for products that weren’t shipped via fulfillment?

No. If a productId is not linked to a fulfillment outbound shipment, the API will reject the request with a 400 error.

 Can I use any GTIN or product reference?

No — you must use the productId that was part of the original shipment (GET /outbound-shipments/{id} helps retrieve them).

 How do I download the return label?

Once the return is accepted, call:
GET /returns/{returnId}/labels
It returns a PDF or PNG (base64), depending on the carrier.

 What are the possible return statuses?

  • Created: return registered

  • Accepted: validated by warehouse

  • Pending: waiting for reception

  • Completed: product received and processed

  • Referenced: return content acknowledged

  • Refused (if applicable)

 How do I know if the warehouse received the return?

Check status = Completed, and inspect:

  • receiptedQuantity

  • receiptedProductState

  • conformity (e.g. Conform, NonConform)

All available in GET /returns/{id}

 What are the return types and reasons?

  • Types:

    • Customer – initiated by seller

    • Carrier – created after failed delivery

  • Customer reasons:

    • ReferenceError, Damaged, Retraction, UnpackingDefect...

  • Carrier reasons:

    • Undeliverable, CustomerRefusal, TransportDamage, NotRetrieved

 Can I track returns per parcel?

Yes — you can filter returns with parcelId and retrieve returns that affected specific shipments.

 Can I cancel a return?

No — returns are not cancellable once created. If not needed, you can let it expire without sending the parcel.

 Is this feature available in sandbox?

There is no sandbox available.

Due to the nature of some of the manual operations involved in processing product data, receiving physical goods, and packaging shipments, along with synchronizing multiple warehouses and databases, conducting complete tests is relatively complicated and thus not provided as a common possibility.

© Octopia 2021 - 2026  —  Legal · API T&C · Octopia T&C · Illegal Content  —  Privacy Policy · Cookie management