Custom returns portal

The returns request and returns order notification can be implemented to support the returns portal.

There are two ways of processing returns using the Shippit APIs. For a simplified return, you can set the return parameter in an order API call to true. Alternatively, you can implement a custom returns integration, using the returns endpoint. This section provides information about setting up your own custom returns integration.

For more information on how to use the different types of returns, see the Returns section in the Developer guide.

Return order

POST /returns/order

The returns endpoint uses v4 of the Shippit API, check that you are using the correct version of the API: https://app.shippit.com/api/4

A Return Order is created when a Returns Request is approved and the shipment has been confirmed.

Shippit sends a notification when a the Return Order is created to a URL you have configured in your Returns Portal settings in Shippit Admin.

Body

{
  "return_order": {
    "return_request_id": "aaaa-1111-bbbb-2222",
    "order_reference": "123456",
    "customer_email": "test@shippit.com",
    "order_api_reference": "abcdef",
    "shippit_api_reference": 180663,
    "date": "2024-05-03T11:31:45+10:00",
    "shipping_method": {
      "code": "standard",
      "source": "shippit",
      "carrier": "eparcel",
      "label": "AusPost Standard Post",
      "tracking_number": "PPsometracking"
    },
    "customer": {
      "email": "test@shippit.com",
      "phone": "0410123456",
      "firstname": "John",
      "lastname": "Wick"
    },
    "return_address": {
      "firstname": "Robert",
      "lastname": "Johns",
      "company": "Harold's Harpoons",
      "phone": "0400000000",
      "street": [
        "110 Rex Road"
      ],
      "suburb": "Sydney",
      "postcode": "2000",
      "region": "New South Wales",
      "region_code": "NSW",
      "country": "Australia",
      "country_code": "AU"
    },
    "shipping_address": {
      "firstname": "John",
      "lastname": "Wick",
      "phone": "0411111111",
      "street": [
        "Level 10",
        "1 Union Street"
      ],
      "suburb": "Pyrmont",
      "postcode": "2000",
      "region": "New South Wales",
      "region_code": "NSW",
      "country": "Australia",
      "country_code": "AU"
    }
  }
}

Return request

POST /returns/request

A Return Request provides a mechanism to query the merchant’s platform for details about an order and its contents.

A return request triggers Shippit to query the Merchant’s platform to retrieve all applicable details required to be provided as part of the Return Request response.

Upon a successful Return Request response, the return details are presented to the customer in the Returns Portal, allowing them to make a selection of the goods to be returned for the order.

Body

{
  "order_reference": "ORDER-10001",
  "email_address": "test@shippit.com"
}