Returns schemas

This section contains the schemas for the Returns API.

Request body schema for return_order

Name Type Required Description
return_request_id string true The id of the corresponding return request that was returned by the ReturnRequest
order_reference string false The reference of the order returned from the corresponding ReturnRequest.
order_api_reference string false The api_reference of the order returned from the corresponding ReturnRequest.
shippit_api_reference integer(int32) true Shippit’s ID for the return order.
date string(date-time) true The date the return order was confirmed.
shipping_method Array, see table true The details of the shipment itself.
customer Array, see table true The details of the customer making the return.
return_address Array, see table true The delivery address to where the order is being returned.
shipping_address Array, see table true The address from where the order is being shipped from.
items Array, see table true The items to be returned in the order.
preferred_refund_method string false The refund method selected by the customer. The available string values are configured from the Returns settings in the Shippit Admin.

Request schema for shipping_method

Name Type Required Description
code string true The service level of the shipment, can be ‘standard’ or ‘express’.
source string true Always ‘shippit’.
carrier string true The carrier used to deliver the return.
label string true The human readable name of the carrier used to deliver the return.
tracking_number string true The tracking number for the return shipment. This is used to receive status updates for the shipment.
courier_job_id any false The ID assigned by some carriers to the shipment / consignment. Depending on the shipment, the field may not be available.
return_method string false Enum: “pickup” “dropoff” “instore_return”
The return method for the order, if present.      

Request schema for customer

Name Type Required Description
id integer false The ID of the record within Shippit Connect
api_reference string false The API Reference provided by the Integration Platform
firstname string false The addressee’s firstname
middlename string false The addressee’s middlename
lastname string false The addressee’s lastname
email string true The email of the customer.

Request schema for return_address

Name Type Required Description
firstname string false The merchant’s firstname
lastname string false The merchant’s lastname
company string false The merchant’s company name
phone string false The merchant’s phone number
street string true The street level address details
suburb string false The suburb of the address
postcode string true The postcode of the address
region string false The region of the address
region_code string false The region code of the address (ISO-3166-2 Subdivision)
country string true The country name (ISO-3166 Country Name)
country_code string true The country code (ISO-3166-2 Alpha 2)

Request schema for shipping_address

Name Type Required Description
firstname string false The addressee’s firstname
middlename string false The addressee’s middlename
lastname string false The addressee’s lastname
company string false The addressee company name
phone string false The addressee’s phone number
street string true The street level address details
suburb string true The suburb of the address
postcode string true The postcode of the address
region string false The region of the address
region_code string false The region code of the address (ISO-3166-2 Subdivision)
country string true The country name (ISO-3166 Country Name)
country_code string true The country code (ISO-3166-2 Alpha 2)

Request schema for items

Name Type Required Description
api_reference string false none
sku string false none
name string false none
qty integer(int32) false none
price integer(int32) false none
reason string false none
condition string false none

Response schema for return_request

Name Type Required Description
id integer true The ID of the return request, this is used to correlate the Return Request with the Return Order
reference string true The order reference number. This is the friendly order reference communicated to end-customers in relation to their order.
api_reference string false The API Reference of the Order, according to the Integration Platform.
date string(date-time) true The date the order was created. The date format is a valid ISO8601 DateTime
customer Array, see table true Details relating to the customer of record for the order
billing_address Array, see table false The Billing Address attached to the order
shipping_address Array, see table true The Shipping Address attached to the order
items Array, see table true 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.
currency_code string false The ISO-4217 Currency Code of the Order
subtotal number(float) false The subtotal of the order.
tax_amount number(float) false The tax amount applicable to the order.
shipping_amount number(float) false The shipping costs applicable to the order.
grand_total number(float) false The grand total of the order, after any discounts, applicable taxes and shipping costs
merchants Array, see table false 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.
updated_at string(date-time) false The date the return request was last updated at. The date format is a valid ISO8601 DateTime
customer_return_charge_currency string false Three letter ISO 4217 currency code that applies to customer_return_charge.

If not provided, the merchant’s currency is used.
customer_return_dropoff_charge number(float) false The amount charged to the customer to process a return dropped off at a PUDO location.
customer_return_pickup_charge number(float) false The amount charged to the customer to process a return picked up from the customer’s address.
expiration_date string(date-time) false The expiry date of the return order, after which returning the order is no longer valid. The date format is a valid ISO8601 DateTime.

Response schema for customer

Name Type Required Description
id integer false The ID of the record within Shippit Connect
api_reference string false The API Reference provided by the Integration Platform
firstname string false The addressee’s firstname
middlename string false The addressee’s middlename
lastname string false The addressee’s lastname
email string true The email of the customer.

Response schema for billing_address

Name Type Required Description
id integer false The ID of the record within the integrated order platform.
api_reference string false The API Reference provided by the Integration Platform
firstname string false The addressee’s firstname
middlename string false The addressee’s middlename
lastname string false The addressee’s lastname
company string false The addressee company name
phone string false The addressee’s phone number
street string true The street level address details
suburb string true The suburb of the address
postcode string true The postcode of the address
region string false The region of the address
region_code string false The region code of the address (ISO-3166-2 Subdivision)
country string true The country name (ISO-3166 Country Name)
country_code string true The country code (ISO-3166-2 Alpha 2)

Response schema for shipping_address

Name Type Required Description
id integer true The ID of the record within the integrated order platform.
api_reference string false The API Reference provided by the Integration Platform
firstname string false The addressee’s firstname
middlename string false The addressee’s middlename
lastname string false The addressee’s lastname
company string false The addressee company name
phone string false The addressee’s phone number
street string true The street level address details
suburb string true The suburb of the address
postcode string true The postcode of the address
region string false The region of the address
region_code string false The region code of the address (ISO-3166-2 Subdivision)
country string true The country name (ISO-3166 Country Name)
country_code string true The country code (ISO-3166-2 Alpha 2)

Response schema for items

Name Type Required Description
id integer true The ID of the item record in Shippit Connect
api_reference string true The ID of the item, each item ID must be unique to the order.
sku string false The item’s stock keeping unit (Item SKU)
name string false The item’s name
weight number(float) false The item’s weight measurement, in kilograms
depth number(float) false The item’s depth measurement, in centimetres
length number(float) false The item’s length measurement, in centimetres
width number(float) false The item’s width measurement, in centimetres
options any false An array of options applicable to the item (ie: colour or size)
qty integer true 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_ordered integer true The qty of the item that was originally ordered, according to the Integration Platform
qty_invoiced integer false The qty of the item that has been invoiced, according to the Integration Platform
qty_shipped integer false The qty of the item that has been marked as shipped according to the Integration Platform
qty_cancelled integer false 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_refunded integer false 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_returned integer false 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.
price number true The item’s price, after any item-level discounts applied
original_price number(float) false 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_amount number(float) false 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.
tax number(float) false The tax amount applicable to the item
is_price_incl_tax boolean false Indicates whether the price fields (original_price, price) includes tax as part of it’s value.
image_url string false The URL of the product image
is_virtual boolean false 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_reason string false The reason why the item cannot be returned.

Response schema for merchants

Name Type Required Description
merchant_id integer true The Shippit Merchant ID
items Array, see table false The items that the Merchant is to be considered for
address Array, see table false The address of the Merchant

Response schema for merchant items

Name Type Required Description
id integer true The ID of the item record in Shippit Connect
api_reference string true The API Reference of the Item, according to the Integration Platform.
sku string true The item’s stock keeping unit (Item SKU)
name string true The item’s name
qty integer false The qty of the item that should be considered for this merchant.

Response schema for merchant address

Name Type Required Description
id integer false The ID of the record within the order platform
api_reference string false The API Reference provided by the Intergration Platform
firstname string false The merchant’s firstname
middlename string false The merchant’s middlename
lastname string false The merchant’s lastname
company string false The merchant’s company name
phone string false The merchant’s phone number
street string true The street level address details
suburb string true The suburb of the address
postcode string true The postcode of the address
region string false The region of the address
region_code string false The region code of the address (ISO-3166-2 Subdivision)
country string true The country name (ISO-3166 Country Name)
country_code string true The country code (ISO-3166-2 Alpha 2)