Returns Workflow (Retours)

This guide demonstrates the complete workflow for handling a customer return through the Wing API v3, from opening the return to shipping the returned parcel back to the warehouse.

Overview

A return is modelled as a new FulfillmentOrder, linked to the original one, carrying only the products actually being returned:

1. Authentication - Obtain an access token
2. Create Return Fulfillment Order - Open a return against an existing order, listing the returned products and quantities
3. Create Return Parcel - Generate the return shipping label

Data model for this workflow

The return FulfillmentOrder belongs to the same Order as the original one, and points back to it via linkedFulfillmentOrderId:

Full vs. partial return

productList on createReturnFulfillmentOrder decides the scope of the return — only the listed fulfillmentOrderProductIds (and their quantity) end up on the return FulfillmentOrder, the rest stays fulfilled on the original one:

Step 1: Authentication

First, obtain an access token using your credentials:

mutation {
  createAccessToken(
    input: { email: "your_email@example.com", password: "your_password" }
  ) {
    accessToken
    refreshToken
    expiresAt
  }
}

Store the accessToken for all subsequent requests.

Step 2: Create the Return Fulfillment Order

Open a return against the original order, listing the returned products by their fulfillmentOrderProductId:

mutation {
  createReturnFulfillmentOrder(
    input: {
      orderId: "ord_abc123xyz"
      service: COLISSIMO
      productList: [{ fulfillmentOrderProductId: "fop_111", quantity: 1 }]
    }
  ) {
    id
    status
    isReturn
    linkedFulfillmentOrderId
  }
}

Response:

{
  "data": {
    "createReturnFulfillmentOrder": {
      "id": "fo_return_789",
      "status": "CREATED",
      "isReturn": true,
      "linkedFulfillmentOrderId": "fo_def456"
    }
  }
}

Important: Save the returned id (fo_return_789) — it is the fulfillmentOrderId used in the next step.

Step 3: Create the Return Parcel

Generate the shipping label for the return:

mutation {
  createFulfillmentReturnParcel(
    input: { fulfillmentOrderId: "fo_return_789" }
  ) {
    id
    status
    parcels {
      id
      trackingId
      trackingURL
      labelURL
    }
  }
}

Response:

{
  "data": {
    "createFulfillmentReturnParcel": {
      "id": "fo_return_789",
      "status": "SHIPPED",
      "parcels": [
        {
          "id": "parcel_return_321",
          "trackingId": "1Z999AA10123456999",
          "trackingURL": "https://track.wing.eu/1Z999AA10123456999",
          "labelURL": "https://labels.wing.eu/parcel_return_321.pdf"
        }
      ]
    }
  }
}

Share the labelURL with the customer (or print it in-warehouse for a warehouse-initiated return), and track the return with the same fulfillmentOrder query used for standard shipments.

Common Errors

Error	Cause	Solution
FULFILLMENT_ORDER_NOT_FOUND	Invalid orderId, or original FO not yet delivered	Verify orderId and that the original FulfillmentOrder exists
INVALID_QUANTITY	Return quantity exceeds the original quantity	Check fulfillmentOrderProductId/quantity against the original order
EMPTY_PRODUCT_LIST	No products specified in productList	Include at least one product to return
PARCEL_ALREADY_CREATED	createFulfillmentReturnParcel called twice	Query the FulfillmentOrder's parcels before retrying

Next Steps

• Learn about Single-Package Order Workflows for the initial shipment
• Explore Multi-Package Order Workflows for split/merge/migrate scenarios
• Check Fulfillment Order to track return status

Related API Operations

• createReturnFulfillmentOrder - Open a return
• createFulfillmentReturnParcel - Generate the return label
• fulfillmentOrder - Track return status
• order - Query the parent order