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.
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
billing_addressobjectOptional- The Billing Address attached to the order
Show child attributesHide child attributes
shipping_addressobjectRequired- The Shipping Address attached to the order
Show child attributesHide child attributes
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
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 ofNULLis 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 ofNULLis 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 ofNULLis returned. 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, aNULLvalue 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.
is_price_incl_taxbooleanOptional- Indicates whether the price fields (
original_price,price) includes tax as part of it's value.
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
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.
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.
shipping_methodobjectRequired- The details of the shipment itself.
Show child attributesHide child attributes
customerobjectRequired- The details of the customer making the return.
Show child attributesHide child attributes
return_addressobjectRequired- The delivery address to where the order is being returned.
Show child attributesHide child attributes
shipping_addressobjectRequired- The address from where the order is being shipped from.
Show child attributesHide child attributes
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"
}
}
}