Returns API

The Returns API backs a custom returns portal: Shippit queries your platform for what an order contains, and notifies you when a return order is created.

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.

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

Endpoints

POST/returns/orderNotify your application that a return order has been created
POST/returns/requestQuery your platform for an order and its returnable items

The return request object

This is what your application returns when Shippit queries it for an order. The details are then presented to the customer in the returns portal.

idintegerRequired

The ID of the return request, this is used to correlate the Return Request with the Return Order

referencestringRequired

The order reference number. This is the friendly order reference communicated to end-customers in relation to their order.

api_referencestringOptional

The API Reference of the Order, according to the Integration Platform.

datestring(date-time)Required

The date the order was created. The date format is a valid ISO8601 DateTime

customerobjectRequired

Details relating to the customer of record for the order

Show child attributesHide child attributes

idintegerOptional: The ID of the record within Shippit Connect
api_referencestringOptional: The API Reference provided by the Integration Platform
firstnamestringOptional: The addressee's firstname
middlenamestringOptional: The addressee's middlename
lastnamestringOptional: The addressee's lastname
emailstringRequired: The email of the customer.

billing_addressobjectOptional

The Billing Address attached to the order

Show child attributesHide child attributes

idintegerOptional: The ID of the record within the integrated order platform.
api_referencestringOptional: The API Reference provided by the Integration Platform
firstnamestringOptional: The addressee's firstname
middlenamestringOptional: The addressee's middlename
lastnamestringOptional: The addressee's lastname
companystringOptional: The addressee company name
phonestringOptional: The addressee's phone number
streetstringRequired: The street level address details
suburbstringRequired: The suburb of the address
postcodestringRequired: The postcode of the address
regionstringOptional: The region of the address
region_codestringOptional: The region code of the address (ISO-3166-2 Subdivision)
countrystringRequired: The country name (ISO-3166 Country Name)
country_codestringRequired: The country code (ISO-3166-2 Alpha 2)

shipping_addressobjectRequired

The Shipping Address attached to the order

Show child attributesHide child attributes

idintegerRequired: The ID of the record within the integrated order platform.
api_referencestringOptional: The API Reference provided by the Integration Platform
firstnamestringOptional: The addressee's firstname
middlenamestringOptional: The addressee's middlename
lastnamestringOptional: The addressee's lastname
companystringOptional: The addressee company name
phonestringOptional: The addressee's phone number
streetstringRequired: The street level address details
suburbstringRequired: The suburb of the address
postcodestringRequired: The postcode of the address
regionstringOptional: The region of the address
region_codestringOptional: The region code of the address (ISO-3166-2 Subdivision)
countrystringRequired: The country name (ISO-3166 Country Name)
country_codestringRequired: The country code (ISO-3166-2 Alpha 2)

itemsarray of objectsRequired

The items contained in the order.

Note: All items from the original order are included in the response, including items that do not have a qty available for return.

Show child attributesHide child attributes

idintegerRequired: The ID of the item record in Shippit Connect
api_referencestringRequired: The ID of the item, each item ID must be unique to the order.
skustringOptional: The item's stock keeping unit (Item SKU)
namestringOptional: The item's name
weightnumber(float)Optional: The item's weight measurement, in kilograms
depthnumber(float)Optional: The item's depth measurement, in centimetres
lengthnumber(float)Optional: The item's length measurement, in centimetres
widthnumber(float)Optional: The item's width measurement, in centimetres
optionsanyOptional: An array of options applicable to the item (ie: colour or size)
qtyintegerRequired: The qty of the item that could be returned by the customer.

This value takes into consideration all available data from the Integration Platform as to the "returnable amount".

In all instances, Connect attempts to determine a suitable amount that is available for return, considering both the qty that was originally ordered, qty shipped to the customer, along with taking into consideration any existing returns, refunds or cancellations.
qty_orderedintegerRequired: The qty of the item that was originally ordered, according to the Integration Platform
qty_invoicedintegerOptional: The qty of the item that has been invoiced, according to the Integration Platform
qty_shippedintegerOptional: The qty of the item that has been marked as shipped according to the Integration Platform
qty_cancelledintegerOptional: The qty of the item that has been cancelled, according to the Integration Platform.

A cancelled item is considered as an item that was ordered, but not yet paid for by the customer.

Note: Not all platforms support the cancellation of an item. In cases where this data is not available, a value of NULL is returned.
qty_refundedintegerOptional: The qty of the item that has been refunded, according to the Integration Platform.

A refunded item is considered as an item that was ordered and invoiced to the customer.

Note: Not all platforms support the refund of an item. In cases where this data is not available, a value of NULL is returned.
qty_returnedintegerOptional: The qty of the item returned, according to the integration platform.

A return item is considered as an item that was shipped to the customer and returned back to the merchant.

Note: Not all platforms support the return of an item. In cases where this data is not available, a value of NULL is returned.
pricenumberRequired: The item's price, after any item-level discounts applied
original_pricenumber(float)Optional: The original price of the item, before any discounts.

Note: Some integration platforms do not support providing data relating to the original price of the item at the time the order was placed. In these instances, a NULL value is returned.
discount_amountnumber(float)Optional: The discount amount applicable to the item. Note: Only item level discounts are considered here. Subtotal & Order level discounts are not considered in this response value.
taxnumber(float)Optional: The tax amount applicable to the item
is_price_incl_taxbooleanOptional: Indicates whether the price fields (original_price, price) includes tax as part of it's value.
image_urlstringOptional: The URL of the product image
is_virtualbooleanOptional: Indicates whether the item is considered as a "virtual" item.

Virtual items are considered non-physical items that do not require shipping. ie: Virtual Gift Cards and Downloadable Content.
non_return_reasonstringOptional: The reason why the item cannot be returned.

currency_codestringOptional

The ISO-4217 Currency Code of the Order

subtotalnumber(float)Optional

The subtotal of the order.

tax_amountnumber(float)Optional

The tax amount applicable to the order.

shipping_amountnumber(float)Optional

The shipping costs applicable to the order.

grand_totalnumber(float)Optional

The grand total of the order, after any discounts, applicable taxes and shipping costs

merchantsarray of objectsOptional

The Shippit Merchant accounts involved.

Note: This field is optional and only provided in some integrations.

It's purpose is to provide a list of the Shippit merchant accounts that are to be considered for the return, based on a merchant's details in relation to the order that has been queried.

Show child attributesHide child attributes

merchant_idintegerRequired

The Shippit Merchant ID

itemsarray of objectsOptional

The items that the Merchant is to be considered for

Show child attributesHide child attributes

idintegerRequired: The ID of the item record in Shippit Connect
api_referencestringRequired: The API Reference of the Item, according to the Integration Platform.
skustringRequired: The item's stock keeping unit (Item SKU)
namestringRequired: The item's name
qtyintegerOptional: The qty of the item that should be considered for this merchant.

addressobjectOptional

The address of the Merchant

Show child attributesHide child attributes

idintegerOptional: The ID of the record within the order platform
api_referencestringOptional: The API Reference provided by the Intergration Platform
firstnamestringOptional: The merchant's firstname
middlenamestringOptional: The merchant's middlename
lastnamestringOptional: The merchant's lastname
companystringOptional: The merchant's company name
phonestringOptional: The merchant's phone number
streetstringRequired: The street level address details
suburbstringRequired: The suburb of the address
postcodestringRequired: The postcode of the address
regionstringOptional: The region of the address
region_codestringOptional: The region code of the address (ISO-3166-2 Subdivision)
countrystringRequired: The country name (ISO-3166 Country Name)
country_codestringRequired: The country code (ISO-3166-2 Alpha 2)

updated_atstring(date-time)Optional

The date the return request was last updated at. The date format is a valid ISO8601 DateTime

customer_return_charge_currencystringOptional

Three letter ISO 4217 currency code that applies to customer_return_charge.

If not provided, the merchant's currency is used.

customer_return_dropoff_chargenumber(float)Optional

The amount charged to the customer to process a return dropped off at a PUDO location.

customer_return_pickup_chargenumber(float)Optional

The amount charged to the customer to process a return picked up from the customer's address.

expiration_datestring(date-time)Optional

The expiry date of the return order, after which returning the order is no longer valid. The date format is a valid ISO8601 DateTime.

Sample responseJSON

{
  "return_request": {
    "id": 1355,
    "reference": "#1001",
    "api_reference": "845450641471",
    "date": "2019-04-11T03:30:30+00:00",
    "customer": {
      "id": 1348,
      "api_reference": "1047141580863",
      "email": "test@example.com",
      "firstname": "John",
      "lastname": "Wick"
    },
    "billing_address": {
      "id": 1291,
      "firstname": "John",
      "lastname": "Wick",
      "street": [
        "10 Flinders Street"
      ],
      "suburb": "Sydney",
      "postcode": "2000",
      "region": "New South Wales",
      "region_code": "NSW",
      "country": "Australia",
      "country_code": "AU"
    },
    "shipping_address": {
      "id": 1290,
      "firstname": "John",
      "lastname": "Wick",
      "street": [
        "10 Flinders Street"
      ],
      "suburb": "Sydney",
      "postcode": "2000",
      "region": "New South Wales",
      "region_code": "NSW",
      "country": "Australia",
      "country_code": "AU"
    },
    "items": [
      {
        "id": 1890,
        "api_reference": "1936837640255",
        "sku": "TACO",
        "name": "Single Taco",
        "weight": 0.5,
        "options": [
          {
            "api_reference": "2380278235199",
            "label": "Title",
            "value": "Default Title"
          }
        ],
        "qty": 1,
        "qty_ordered": 1,
        "qty_shipped": 0,
        "qty_refunded": 0,
        "non_return_reason": "This product cannot be returned because it is a sale item",
        "price": 20,
        "original_price": 20,
        "discount_amount": 0,
        "tax": 2,
        "is_price_incl_tax": true,
        "image_url": "https://cdn.shopify.com/s/files/1/0083/3798/1503/products/Taco.jpeg?v=1554966383",
        "is_virtual": false
      }
    ],
    "currency_code": "AUD",
    "subtotal": 20,
    "tax_amount": 2,
    "shipping_amount": 10,
    "grand_total": 32,
    "merchants": [],
    "created_at": "2019-04-12T00:07:19+00:00",
    "updated_at": "2019-04-12T00:07:19+00:00"
  }
}

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.

This operation does not require authentication.

Response codes

Status	Meaning	Description
200	OK	The return request order was found and has data available for a response.
404	Not Found	The completed order details could not be found based on the provided `order_reference` and `email_address`
502	Bad Gateway	The return request order details could not be fetched from the connected Order Management Platform due to a request failure when communicating with the Order Management Platform.

RequestJSON

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

Return order

POST/returns/order

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.

This operation does not require authentication.

Parameters

return_request_idstringRequired

The id of the corresponding return request that was returned by the ReturnRequest

order_referencestringOptional

The reference of the order returned from the corresponding ReturnRequest.

order_api_referencestringOptional

The api_reference of the order returned from the corresponding ReturnRequest.

shippit_api_referenceinteger(int32)Required

Shippit's ID for the return order.

datestring(date-time)Required

The date the return order was confirmed.

shipping_methodobjectRequired

The details of the shipment itself.

Show child attributesHide child attributes

codestringRequired: The service level of the shipment, can be 'standard' or 'express'.
sourcestringRequired: Always 'shippit'.
carrierstringRequired: The carrier used to deliver the return.
labelstringRequired: The human readable name of the carrier used to deliver the return.
tracking_numberstringRequired: The tracking number for the return shipment. This is used to receive status updates for the shipment.
courier_job_idanyOptional: The ID assigned by some carriers to the shipment / consignment. Depending on the shipment, the field may not be available.
return_methodstringOptional: Enum: "pickup" "dropoff" "instore_return"
The return method for the order, if present.

customerobjectRequired

The details of the customer making the return.

Show child attributesHide child attributes

idintegerOptional: The ID of the record within Shippit Connect
api_referencestringOptional: The API Reference provided by the Integration Platform
firstnamestringOptional: The addressee's firstname
middlenamestringOptional: The addressee's middlename
lastnamestringOptional: The addressee's lastname
emailstringRequired: The email of the customer.

return_addressobjectRequired

The delivery address to where the order is being returned.

Show child attributesHide child attributes

firstnamestringOptional: The merchant's firstname
lastnamestringOptional: The merchant's lastname
companystringOptional: The merchant's company name
phonestringOptional: The merchant's phone number
streetstringRequired: The street level address details
suburbstringOptional: The suburb of the address
postcodestringRequired: The postcode of the address
regionstringOptional: The region of the address
region_codestringOptional: The region code of the address (ISO-3166-2 Subdivision)
countrystringRequired: The country name (ISO-3166 Country Name)
country_codestringRequired: The country code (ISO-3166-2 Alpha 2)

shipping_addressobjectRequired

The address from where the order is being shipped from.

Show child attributesHide child attributes

firstnamestringOptional: The addressee's firstname
middlenamestringOptional: The addressee's middlename
lastnamestringOptional: The addressee's lastname
companystringOptional: The addressee company name
phonestringOptional: The addressee's phone number
streetstringRequired: The street level address details
suburbstringRequired: The suburb of the address
postcodestringRequired: The postcode of the address
regionstringOptional: The region of the address
region_codestringOptional: The region code of the address (ISO-3166-2 Subdivision)
countrystringRequired: The country name (ISO-3166 Country Name)
country_codestringRequired: The country code (ISO-3166-2 Alpha 2)

itemsarray of objectsRequired

The items to be returned in the order.

Show child attributesHide child attributes

api_referencestringOptional: none
skustringOptional: none
namestringOptional: none
qtyinteger(int32)Optional: none
priceinteger(int32)Optional: none
reasonstringOptional: none
conditionstringOptional: none

preferred_refund_methodstringOptional

The refund method selected by the customer. The available string values are configured from the Returns settings in the Shippit Admin.

Response codes

Status	Meaning	Description
200	OK	The response [success] the webhook expects from your application endpoint.

Notification bodyJSON

{
  "return_order": {
    "return_request_id": "aaaa-1111-bbbb-2222",
    "order_reference": "123456",
    "customer_email": "test@example.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@example.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"
    }
  }
}