Track your returns

The simplest solution for tracking returns is by providing the information about the returned parcel by means of a delivery leg.

A delivery leg is marked as a return by setting the RETURN value to the DeliveryInformation.direction attribute in the delivery object of the delivery leg.

The delivery leg should include the return tracking identifier for the parcel (it is usually different to the outgoing tracking identifier), and ideally information about the carrier.

Steps:

Open the resource POST Create or update a delivery leg .
Update the body with the following JSON object:

Copy

Copied

{
  "trackingIdentifier": "TRACK-RETURNS-001",
  "delivery": {
    "direction": "RETURN"
  },
  "carrierCode": "CHRONOPOST"
}

Send the request.
Expect a successful response with 204 No Content response code.

Once the delivery leg is created, Metapack will collect the tracking events for the returned parcel. These events will be included in the tracking history when retrieving the parcel journey using the return tracking identifier.

Open the resource GET Retrieve the parcel journeys for an order or a parcel .
In the tab Parameters , set the value of the query parameter trackingIdentifier to TRACK-RETURNS-001 .
Remove all other query parameters so that only the query parameter trackingIdentifier is retained.
Send the request to retrieve the parcel journey using the tracking identifier of the parcel.
Expect a successful response with a 200 OK response code and the following JSON body:

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "RETURN",
            "carrierServiceType": "TRACKED",
            "returnType": "ON_DEMAND"
        },
        "parcel": {
            "deliveryLegs": [
                {
                    "carrierCode": "CHRONOPOST",
                    "carrierTrackingURL": "https://www.chronopost.fr/tracking-no-cms/suivi-page?langue=fr_FR&listeNumerosLT=TRACK-RETURNS-001",
                    "trackingIdentifier": "TRACK-RETURNS-001",
                    "carrierDisplayName": "Chronopost",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

In this simple example, the parcel journey is enriched with the following information:

delivery : information about the type of delivery
- type : defaults to HOME delivery. Supported types are [ HOME, PUDO, STORE ] .
- direction : set to RETURN when the delivery leg was created.
- carrierServiceType : defaults to TRACKED . Supported services are [ TRACKED, UNTRACKED ] .
- returnType : describes the type of returns label which can be pre-printed or requested on demand. It defaults to ON_DEMAND .
parcel.deliveryLegs :
- carrierTrackingURL : a link for tracking the parcel directly on the carrier website.
- carrierDisplayName : the name of the carrier returning the parcel.
- finalDeliveryLeg : an indicator that identifies the delivery leg for the final mile delivery.
parcel.items : an array used to identify items within the parcel.
trackingEvents : an array that will contain all the tracking events that compose the tracking history of the parcel.

Inform your shoppers of the progress of their returns

You can inform your shoppers of the progress of their returns by publishing events by means of delivery leg event using the tracking identifiers of the parcels being returned.

Find out about the list of supported events for handling returns in Supported tracking events/Return events section of the documentation.

In this example, a RETURN_APPROVED delivery leg event is created in order to inform a shopper that their request to return items has been accepted. This event uses the return tracking identifier TRACK-RETURNS-001.

Steps:

Open the resource POST Add tracking events to a delivery leg .
Update the body with the following JSON object:

Copy

Copied

{
  "trackingIdentifier": "TRACK-RETURNS-001",
  "eventCode": "RETURN_APPROVED",
  "eventDate": "2022-11-10T13:35:05.306Z",
  "eventTimeZone": "Europe/London"
}

Send the request to create the delivery leg event.
Expect a successful response with 204 No Content response code.

The parcel journey that tracks the parcel being returned will include the tracking events provided by the carrier alongside the events that you have provided as part of your process for handling returns.

Open the resource GET Retrieve the parcel journeys for an order or a parcel .
In the tab Parameters , set the value of the query parameter trackingIdentifier to TRACK-RETURNS-001 .
Remove all other query parameters so that only the query parameter trackingIdentifier is retained.
Send the request to retrieve the parcel journey using the tracking identifier of the parcel.
Expect a successful response with a 200 OK response code and the following JSON body:

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "RETURN",
            "carrierServiceType": "TRACKED",
            "returnType": "ON_DEMAND"
        },
        "parcel": {
            "deliveryLegs": [
                {
                    "carrierCode": "CHRONOPOST",
                    "carrierTrackingURL": "https://www.chronopost.fr/tracking-no-cms/suivi-page?langue=fr_FR&listeNumerosLT=TRACK-RETURNS-001",
                    "trackingIdentifier": "TRACK-RETURNS-001",
                    "carrierDisplayName": "Chronopost",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": [
            {
                "eventDate": "2022-11-10T13:35:05.306Z",
                "eventTimeZone": "Europe/London",
                "trackingIdentifier": "TRACK-RETURNS-001",
                "eventCode": "RETURN_APPROVED",
                "eventDescription": "Return request approved",
                "statusCode": "RETURN_REQUEST_IN_PROGRESS",
                "statusDescription": "Return request in progress",
                "eventCategory": "HAPPY"
            }
        ],
        "latestTrackingStatus": {
            "eventDate": "2022-11-10T13:35:05.306Z",
            "eventTimeZone": "Europe/London",
            "trackingIdentifier": "TRACK-RETURNS-001",
            "eventCode": "RETURN_APPROVED",
            "eventDescription": "Return request approved",
            "statusCode": "RETURN_REQUEST_IN_PROGRESS",
            "statusDescription": "Return request in progress",
            "eventCategory": "HAPPY"
        }
    }
]

You can inform your shopper that their returns has been received by sending a RETURN_RECEIVED delivery leg event and that their refund has been issued using a RETURN_COMPLETED delivery leg event.

Steps:

Open the resource POST Add tracking events to a delivery leg .
Update the body with the following JSON object:

Copy

Copied

{
  "trackingIdentifier": "TRACK-RETURNS-001",
  "eventCode": "RETURN_RECEIVED",
  "eventDate": "2022-11-15T09:15:45.987Z",
  "eventTimeZone": "Europe/London"
}

Send the request to create the delivery leg event.
Expect a successful response with 204 No Content response code.
Update the body with the following JSON object:

Copy

Copied

{
  "trackingIdentifier": "TRACK-RETURNS-001",
  "eventCode": "RETURN_COMPLETED",
  "eventDate": "2022-11-15T10:00:00.000Z",
  "eventTimeZone": "Europe/London"
}

Send the request to create the delivery leg event.
Expect a successful response with 204 No Content response code.

These delivery leg events will be included in the tracking history for the returned parcel.

Link your returns with your orders

You can easily link the parcels being returned to the orders for which items are no longer wanted by your shoppers. This is achieved by including the field Order.orderRef to the order object of the delivery leg with the same reference as the one from the original order.

In this example, an order with the reference ORDER-NOT-WANTED is shipped using a single parcel with the outbound tracking identifier TRACK-NOT-WANTED-001. The items from the order are then returned using a single parcel with the return tracking identifier TRACK-RETURNS-NOT-WANTED-001.

Steps:

Open the resource POST Create or update a delivery leg .
Update the body with the following JSON object:

Copy

Copied

{
  "trackingIdentifier": "TRACK-NOT-WANTED-001",
  "order": {
    "orderRef": "ORDER-NOT-WANTED"
  }
}

Send the request to create the first parcel used to ship the order.
Expect a successful response with 204 No Content response code.
Update the body with the following JSON object:

Copy

Copied

{
  "trackingIdentifier": "TRACK-RETURNS-NOT-WANTED-001",
  "order": {
    "orderRef": "ORDER-NOT-WANTED"
  },
  "delivery": {
    "direction": "RETURN"
  } 
}

Send the request to create the parcel that will be returned.
Expect a successful response with 204 No Content response code.

All the parcel journeys that tracks the delivery of the order and the parcel being returned are retrieved in a single request using the order reference.

Open the resource GET Retrieve the parcel journeys for an order or a parcel .
In the tab Parameters , set the value of the query parameter orderRef to ORDER-NOT-WANTED .
Remove all other query parameters so that only the query parameter orderRef is retained.
Send the request to retrieve the parcel journey using the order reference.
Expect a successful response with a 200 OK response code and the following JSON body:

Copy

Copied

[
    {
        "delivery": {
            "type": "HOME",
            "direction": "RETURN",
            "carrierServiceType": "TRACKED",
            "returnType": "ON_DEMAND"
        },
        "order": {
            "orderRef": "ORDER-NOT-WANTED"
        },
        "parcel": {
            "deliveryLegs": [
                {
                    "trackingIdentifier": "TRACK-RETURNS-NOT-WANTED-001",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    },
    {
        "delivery": {
            "type": "HOME",
            "direction": "OUTBOUND",
            "carrierServiceType": "TRACKED"
        },
        "order": {
            "orderRef": "ORDER-NOT-WANTED"
        },
        "parcel": {
            "deliveryLegs": [
                {
                    "trackingIdentifier": "TRACK-NOT-WANTED-001",
                    "finalDeliveryLeg": true
                }
            ],
            "items": []
        },
        "trackingEvents": []
    }
]

The parcel journey marked for returns is included alongside the parcel journey that delivered the order.