API documentation API console
Following API is designed to provide a complete set of tools to integrate with Intelligentreturns
API entry point https://intelligentreturns.net/api
Request and response formats Format depends on url path. Can be JSON or XML. JSON by default.
We encourage Intelligentreturns API users to choose a JSON format.
XML format is available only to support legacy software.
Request Method Request method must always be POST
XML special characters & should be replaced by &
< should be replaced by &lt;
> should be replaced by &gt;
Text fields length Each text field must not exceed 255 symbols length
Request Encoding Must be UTF-8
Server Timezone UTC

General Error codes

Error code Description
internal Internal server error
request_wrong Requested data structure is incorrect
login_empty 'login' POST field is empty
api_key_empty 'api_key' POST field is empty
ip_blocked Your IP was blocked due to many incorrect log in attempts
access_denied Incorrect 'login' or 'api_key'
request_empty 'request' POST field is empty
json_invalid Requested JSON is invalid (in the 'request' POST field)
xml_invalid Requested XML is invalid (in the 'request' POST field)
unknown_call API method does not exist

Input data


Each API request requires login and api key keys sent via POST
Login is your account login.
API key can be found on profile page. To access a profile page, you must be logged in to your account panel.

Output data


Incorrect login or API key

{
    "error": {
        "code": "access_denied",
        "message": [
            "Access denied"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>access_denied</code>
    <message>Access denied</message>
</error>
                                

Input data


Order info (* required)

Key Type Desc
order_reference * string(255) Order reference. Must be unique if "overwrite_data" flag set as FALSE.
order_date * string | int mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
currency_code * string(3) Currency code(3 letters) ISO_4217
overwrite_data boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
Use this field as TRUE to overwrite existing order's data. If order does not exists, then new order will be created.
Please note, that you can add or remove order's items using this field by providing a new items list. However, items that have already been returned cannot be removed
rma string(255) Code that will allow a customer to return an item after return policy has been expired
phone string(255) Phone
email string(255) Email
export_date int Unix timestamp of export date. Default value, will be applied to all items, if not specified in corresponding item field
export_awb string(255) Export air waybill. Default value, will be applied to all items, if not specified in corresponding item field
export_carrier_name string(255) Exporter company. Default value, will be applied to all items, if not specified in corresponding item field
free_return boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
TRUE will set a 100% discount on return shipping cost for the customer.

Address info

Key Type Desc
contact_name string(255) Customer full name (Person)
company_name string(255) Company name
country string(2) Country code (ISO 3166-1 alpha-2)
state string(255) Please, provide a state ISO code for a following countries:
  • AU
  • US
  • CA
Customer's state.
zip string(255) Zip/Post code
city string(255) City
suburb string(255) Suburb
addr1 string(255) Address line 1
addr2 string(255) Address line 2
addr3 string(255) Address line 3
neighborhood string(255) Neighborhood. Available only for Mexico

Item info (* required)

Key Type Desc
sku_code * string(255) Item SKU code
sku_desc * string(255) Item SKU description
quantity * int Number of items sold
price * double Price of 1 item
weight double Weight of 1 item. Default value: 1 (K/L).
weight_uom string(1) K / L (1 letter). Default value: K
length double Length of 1 item
width double Width of 1 item
height double Height of 1 item
dimensions_uom string(2) cm, mm, in
country_code string(2) Country manufacturer code (ISO 3166-1 alpha-2)
hs_code string(255) Harmonization code
img_path string(255) Link to item image
dangerous_goods string(255) Possible values: Yes/No
export_date int Unix timestamp of export date
export_awb string(255) Export air waybill
export_carrier_name string(255) Exporter company
sku_url string(255) Item SKU url
tracking string(255) Item tracking number

You can provide an order data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/orders/create/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "order":
    {
        "order_reference":"1000000000000",
        "order_date":"10/20/2015",
        "rma": "12345",
        "contact_name":"John Smith",
        "company_name":"",
        "addr1":"6 Semaphore Close Mount Pleasant",
        "addr2":"",
        "addr3":"",
        "city":"Christchurch",
        "zip":"8081",
        "state":"qwe",
        "country":"NZ",
        "phone":"+102030405060",
        "email":"john.smith@googlemail.com",
        "currency_code":"AUD",
        "export_awb":"32153454GB",
        "export_carrier_name":"USPS",
        "free_return":true,
        "item":[
            {
                "sku_code":"QWE123",
                "sku_desc":"Black Sculpting & Smoothing Shapewear Body Suit-EUR 38 (M)",
                "quantity":"5",
                "price":"100",
                "weight":"1",
                "length":"2",
                "width":"3",
                "height":"4",
                "dimensions_uom":"mm",
                "hs_code":"999999",
                "country_code":"GB",
                "img_path":"https://intelligentreturns.net/assets/frontend/img/rebound_logo.png",
                "dangerous_goods":"Yes",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS",
                "sku_url": "http://domain.com/sku-url",
                "tracking": "123456789"
            },
            {
                "sku_code":"QWE456",
                "sku_desc":"Black Halterneck Corset",
                "quantity":"10",
                "price":"200",
                "weight":"0.86",
                "length":"10",
                "width":"10",
                "height":"10",
                "dimensions_uom":"mm",
                "hs_code":"999999",
                "country_code":"GB",
                "img_path":"https://intelligentreturns.net/assets/frontend/img/rebound_logo.png",
                "dangerous_goods":"Yes",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS",
                "sku_url": "http://domain.com/sku-url",
                "tracking": "123456780"
            }
        ]
    }
}

XML

URL:
https://intelligentreturns.net/api/orders/create/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<order>
    <order_reference>12312355</order_reference>
    <order_date>2015/05/30</order_date>
    <currency_code>EUR</currency_code>
    <phone>+010557779</phone>
    <email>doe@gmail.com</email>
    <export_awb>444444US</export_awb>
    <export_carrier_name>USPS</export_carrier_name>
    <free_return>true</free_return>
    <contact_name>John Doe</contact_name>
    <company_name></company_name>
    <country>GB</country>
    <state>NY</state>
    <zip>20000</zip>
    <city>some address</city>
    <addr1>address line</addr1>
    <addr2></addr2>
    <addr3></addr3>
    <item>
        <sku_code>ASD111</sku_code>
        <sku_desc>Black Sculpting &amp; Smoothing Shapewear Body Suit-EUR 38 (M)</sku_desc>
        <quantity>5</quantity>
        <price>100</price>
        <weight>0.3</weight>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <country_code>CN</country_code>
        <hs_code>5905954</hs_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>No</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
        <sku_url>http://domain.com/sku-url</sku_url>
        <tracking>123456789</tracking>
    </item>
    <item>
        <sku_code>UN-12322;28</sku_code>
        <sku_desc>Black Halterneck &gt; Corset</sku_desc>
        <quantity>10</quantity>
        <price>200</price>
        <weight>0.86</weight>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <country_code>GB</country_code>
        <hs_code>4331767</hs_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>No</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
        <sku_url>http://domain.com/sku-url</sku_url>
        <tracking>123456780</tracking>
    </item>
</order>

Output data


Order created successfully:

{
    "success": {
        "message": "Order successfully created",
        "order_reference": "1000000000000",
        "order_id": 10000
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<success>
    <message>Order successfully created</message>
    <order_reference>12312355</order_reference>
    <order_id>10000000</order_id>
</success>

Incorrect order data:

{
    "error": {
        "code": "order_incorrect",
        "message": [
            "Incorrect order data. Check fields: quantity,price"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>order_incorrect</code>
    <message>Incorrect order data. Check fields: quantity,price</message>
</error>

Order reference is already exists:

{
    "error": {
        "code": "order_exists",
        "message": [
            "Order reference is already exists"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>order_exists</code>
    <message>Order reference is already exists</message>
</error>

JSON is not valid:

{
    "error": {
        "code": "json_invalid",
        "message": [
            "JSON is not valid"
        ]
    }
}
        

XML is not valid:

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>xml_invalid</code>
    <message>XML is not valid</message>
</error>

Error codes

Error code Description
order_incorrect Incorrect order data. See detailed description in error message
order_exists Order with requested order_reference is already exists
cannot_update_order Some order items cannot be updated because they have already been returned
cannot_create_order Order Create method is temporary unavailable

Input data


Order info

Key Type Value
type enum Can be 'id' or 'reference'
val string(255) id or reference value to search
You can get order by internal id or reference

You can provide an order data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/orders/get/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "order":
    {
        "type":"reference",
        "val":"600090343"
    }
}

XML

URL:
https://intelligentreturns.net/api/orders/get/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<order>
    <type>reference</type>
    <val>600090343</val>
</order>

Output data


Data found:

If order was found, you will receive data in success field of JSON or XML format (depends on what format you've requested)
You can see the description of the fields in the previous method. Create order

JSON response example:

{
    "success": {
        "id": "3103",
        "order_reference": "12312359",
        "order_date": "1432958400",
        "contact_name": "John Doe",
        "company_name": "",
        "addr1": "address line",
        "addr2": "",
        "addr3": "",
        "city": "some address",
        "zip": "20000",
        "state": "NY",
        "country": "GB",
        "phone": "+010557779",
        "email": "doe@gmail.com",
        "currency_code": "EUR",
        "rma": "",
        "export_awb": "444444US",
        "export_carrier_name": "USPS",
        "item": [
            {
                "sku_code": "ASD111",
                "sku_desc": "Black Sculpting  Smoothing Shapewear Body Suit-EUR 38 (M)",
                "quantity": "5",
                "price": "100",
                "weight": "0.3",
                "weight_uom": "",
                "length": "0",
                "width": "0",
                "height": "0",
                "dimensions_uom": "mm",
                "hs_code": "5905954",
                "country_code": "CN",
                "img_path": "",
                "dangerous_goods":"Yes",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS",
                "sku_url": "http://domain.com/sku-url"
            },
            {
                "sku_code": "UN-12322;28",
                "sku_desc": "Black Halterneck  Corset",
                "quantity": "10",
                "price": "200",
                "weight": "0.86",
                "weight_uom": "",
                "length": "0",
                "width": "0",
                "height": "0",
                "dimensions_uom": "mm",
                "hs_code": "4331767",
                "country_code": "GB",
                "img_path": "",
                "dangerous_goods":"No",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS",
                "sku_url": "http://domain.com/sku-url"
            }
        ]
    }
}

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <id>3103</id>
    <order_reference>12312359</order_reference>
    <order_date>1432958400</order_date>
    <contact_name>John Doe</contact_name>
    <company_name></company_name>
    <addr1>address line</addr1>
    <addr2></addr2>
    <addr3></addr3>
    <city>some address</city>
    <zip>20000</zip>
    <state>NY</state>
    <country>GB</country>
    <phone>+010557779</phone>
    <email>doe@gmail.com</email>
    <currency_code>EUR</currency_code>
    <rma></rma>
    <export_awb>444444US</export_awb>
    <export_carrier_name>USPS</export_carrier_name>
    <item>
        <sku_code>ASD111</sku_code>
        <sku_desc>Black Sculpting  Smoothing Shapewear Body Suit-EUR 38 (M)</sku_desc>
        <quantity>5</quantity>
        <price>100</price>
        <weight>0.3</weight>
        <weight_uom></weight_uom>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>5905954</hs_code>
        <country_code>CN</country_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>No</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
        <sku_url>http://domain.com/sku-url</sku_url>
    </item>
    <item>
        <sku_code>UN-12322;28</sku_code>
        <sku_desc>Black Halterneck  Corset</sku_desc>
        <quantity>10</quantity>
        <price>200</price>
        <weight>0.86</weight>
        <weight_uom></weight_uom>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>4331767</hs_code>
        <country_code>GB</country_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>No</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
        <sku_url>http://domain.com/sku-url</sku_url>
    </item>
</success>

Order not found:

{
    "error": {
        "code": "order_nx",
        "message": [
            "Order not found"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>order_nx</code>
    <message>Order not found</message>
</error>

Error codes

Error code Description
order_nx Order was not found

Input data


You can delete order by internal id or reference
URL:
https://intelligentreturns.net/api/orders/delete
Key Type Value
type enum Can be 'id' or 'reference'
val string(255) id or reference value to search

You can provide an order data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/orders/delete/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "order":
    {
        "type":"reference",
        "val":"600090343"
    }
}

XML

URL:
https://intelligentreturns.net/api/orders/delete/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<order>
    <type>reference</type>
    <val>600090343</val>
</order>

Output data


Order successfully deleted:

{
    "success": {
        "message": "Order successfully deleted"
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<success>
    <message>Order successfully deleted</message>
</success>

Order not found:

{
    "error": {
        "code": "order_nx",
        "message": [
            "Order not found"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>order_nx</code>
    <message>Order not found</message>
</error>
        

Error codes

Error code Description
order_nx Order was not found
cannot_delete_order Some items of this order have been already returned

Input data


Information of return (* required)

Key Type Desc
order_reference * string(255) order reference
date_added string | int Return booking date, current time by default. Allowed date formats: mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp
carrier string(255) Deprecated. Consider to use service_id field instead
service string(255) Deprecated. Consider to use service_id field instead
Shipping service type. Required is one of the following carriers was chosen:
  • 'ACP':
    • 'Ground'
    • 'Priority'
  • 'ASM':
    • 'home_collection'
  • 'Hermes':
    • 'home_collection'
    • 'drop_off'
service_id (Preferred) int Shipping service id.
Refer to the Request for prices method to get a service_id
View list of all carrier services
Please note, carrier and service fields will be ignored in case service_id is populated
Either service_id or carrier must be provided
label_format string(255) Shipping label format output.
Available for following carriers:
  • Royal Mail
    • pdf_6x4 (by default)
    • pdf_a4
    • png
  • MyPack
    • pdf_6x4 (by default)
    • pdf_a4
    • png
  • Direct Link
    • pdf_6x4 (by default)
    • pdf_a4
    • png
  • nzpost
    • pdf_6x4 (by default)
    • pdf_a4
    • png
  • AnPost
    • pdf_6x4 (by default)
    • pdf_a4
    • png
  • Royale
    • pdf_6x4 (by default)
    • pdf_a4
    • png
Please note, that other carriers have default label format, provided by carrier's internal API. API error will be raised when incorrect label format requested. Please, use this field only to specify format for carriers listed above
tracking string(255) Tracking number.
Please, note! This field has to be provided if a return has been already booked/registered without using the Intelligentreturns software.
In this case, return will be saved and thereafter will receive tracking updates, but the booking process will be omitted.
-
Otherwise, omit this field or leave it blank, then a return will registered by the Intelligentreturns software and will acquire tracking number automatically.
currency_code string(3) Currency code(3 letters) ISO_4217
phone string(255) Phone
email string(255) Email
display_id string(32) An additional information, which will be displayed on the shipping label (if it is possible). Max length 32 characters
Please note, that Hermes carrier limits display_id to 20 characters
external_id string(255) Alphanumeric value. Must be unique for each return. This field can be used in /returns/get/ method
add_items_data_to_order boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
    Please, set as TRUE in the following cases:
  • You do not provide us orders information. In this case our system will automatically populate orders items information based on returned items
  • You need to to add this return's items to the correspondent order.
If this field is set to "1" or "true", then items difference between order and return will not be checked. All items from the current request will be added into the corresponding order instead. Such order will be found by the "order_reference" field.
export_date int Unix timestamp of export date. Default value, will be applied to all items, if not specified in corresponding item field
export_awb string(255) Export air waybill. Default value, will be applied to all items, if not specified in corresponding item field
export_carrier_name string(255) Exporter company. Default value, will be applied to all items, if not specified in corresponding item field
verification_entity boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
dangerous_goods string(255) Possible values: Yes/No. Default value, will be applied to all items, if not specified in corresponding item field
final_disposition string(255) Can be 'return' or 'destroy'. Will be applied to all items, if not specified in corresponding item field
collection_date object Collection date is available only for home_collection service types.
If not specified, then the next available working day will be chosen. collection_date fields
collection_address object Collection address is available only for home_collection service types.
If not specified, then origin address will be used instead
collection_address fields
drop_off_point_id string(255) Id of selected drop off point
Required for following services:
service_id Carrier name Service name
52 Box It Parcel Locker
53 Box It Parcel Shop
58 BoxBerry Parcel Shop
67 Parcel Point ParcelPoint Drop Off
special_instruction string(255) Special instruction
Used for following services:
service_id Carrier name Service name
66 Parcel Point ParcelPoint Home Collection
booking_type int Return Booking type
Possible values:
  • 1 - Requested by customer (default)
  • 2 - Created in advance

Address Info

Key Type Desc
name * string(255) Customer full name (Person)
company_name string(255) Company name
country * string(255) Customer's country code (ISO 3166-1 alpha-2)
state * string(255) Please, provide a state ISO code for a following countries:
  • AU
  • US
  • CA
Customer's state.
Not required for following countries:
  • GB
  • UK
  • IL
  • DE
  • FR
  • NL
  • IE
  • SE
  • IT
  • DK
  • AT
  • LU
  • CZ
  • BE
  • BG
  • HR
  • CY
  • FI
  • GR
  • HU
  • MT
  • PL
  • PT
  • RO
  • SK
  • SI
  • EE
  • LV
  • LT
  • NZ
zip * string(255) Zip/Post code
Not required for following countries:
  • HK
  • IE
  • IL
city * string(255) City. Not mandatory for AU
suburb string(255) Suburb. Mandatory for AU
addr1 * string(255) Address line 1
addr2 string(255) Address line 2
addr3 string(255) Address line 3
neighborhood string(255) Neighborhood. Available only for Mexico
final_dest_name string(255) Final destination contact name
final_dest_company_name string(255) Final destination company name
final_dest_id string(255) Final destination address ID. Can be provided instead of full final destination address (fields below), in this case destination address fields will be ignored.
final_dest_country string(2) Final destination country code (ISO 3166-1 alpha-2)
final_dest_state string(255) Final destination State
final_dest_zip string(255) Final destination Zip/Post code
final_dest_city string(255) Final destination City
final_dest_suburb string(255) Final destination Suburb
final_dest_addr1 string(255) Final destination Address line 1
final_dest_addr2 string(255) Final destination Address line 2
final_dest_addr3 string(255) Final destination Address line 3
final_dest_neighborhood string(255) Final destination neighborhood. Available only for Mexico

collection_date

Key Type Desc
date string(10) Collection date in yyyy/mm/dd format
time_from string(5) Collection "time from" in hh:mm format
time_to string(5) Collection "time to" in hh:mm format

collection_address (Not required)

Key Type Desc
state * string(255) collection address state.
Not required for following countries:
  • GB
  • UK
  • IL
  • DE
  • FR
  • NL
  • IE
  • SE
  • IT
  • DK
  • AT
  • LU
  • CZ
  • BE
  • BG
  • HR
  • CY
  • FI
  • GR
  • HU
  • MT
  • PL
  • PT
  • RO
  • SK
  • SI
  • EE
  • LV
  • LT
  • NZ
zip * string(255) Zip/Post code
city * string(255) City. Not mandatory for AU
suburb string(255) Suburb. Madatory for AU
addr1 * string(255) Address line 1
addr2 string(255) Address line 2
addr3 string(255) Address line 3

Item info (Not Required)

Key Type Desc
sku_code * string(255) Item SKU code
sku_desc * string(255) Item SKU description
quantity * int Number of items sold
price * double Price of 1 item
weight double Weight of 1 item. Default value: 1 (K/L).
weight_uom string(1) K / L (1 letter). Default value: K
length double Length of 1 item
width double Width of 1 item
height double Height of 1 item
dimensions_uom string(2) cm, mm, in
country_code string(2) Country manufacturer code(2 letters)
hs_code string(255) Harmonization code
img_path string(255) Link to item image
dangerous_goods string(255) Possible values: Yes/No
export_date int Unix timestamp of export date
export_awb string(255) Export air waybill
export_carrier_name string(255) Exporter company
sku_url string(255) URL to assist in verification
tracking string(255) Item tracking number
final_dest_name string(255) Final destination contact name
final_dest_company_name string(255) Final destination company name
final_dest_id string(255) Final destination address ID. Can be provided instead of full final destination address (fields below), in this case destination address fields will be ignored.
final_dest_country string(2) Final destination country code (ISO 3166-1 alpha-2)
final_dest_state string(255) Final destination State
final_dest_zip string(255) Final destination Zip/Post code
final_dest_city string(255) Final destination City
final_dest_suburb string(255) Final destination Suburb
final_dest_addr1 string(255) Final destination Address line 1
final_dest_addr2 string(255) Final destination Address line 2
final_dest_addr3 string(255) Final destination Address line 3
final_dest_neighborhood string(255) Final destination neighborhood. Available only for Mexico
verification_entity boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
final_disposition string(255) Can be 'return' or 'destroy'.

You can provide a return data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/returns/create/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "return":
    {
        "order_reference":"12312355",
        "name":"John Doe",
        "phone":"+010557779",
        "email":"doe@gmail.com",
        "addr1":"City Hall",
        "addr2":"24 Eagle Street, Room 102",
        "addr3":"",
        "city":"Albany",
        "zip":"12207",
        "state":"NY",
        "country":"US",
        "display_id":"123123123",
        "final_dest_id": "Default",
        "final_dest_addr1":"Telford Transport Solutions Ltd",
        "final_dest_addr2":"Stafford Park 12",
        "final_dest_addr3":"",
        "final_dest_city":"Telford",
        "final_dest_zip":"TF3 3BJ",
        "final_dest_state":"West Midlands",
        "final_dest_country":"UK",
        "carrier":"acp",
        "service":"ground",
        "item":[
            {
                "sku_code":"ASD111",
                "sku_desc":"Black Sculpting & Smoothing Shapewear Body Suit-EUR 38 (M)",
                "quantity":"5",
                "price":"100",
                "weight":"0.3",
                "length":"10",
                "width":"10",
                "height":"10",
                "dimensions_uom":"mm",
                "hs_code":"5905954",
                "country_code":"CN",
                "img_path":"https://intelligentreturns.net/assets/frontend/img/rebound_logo.png",
                "dangerous_goods":"Yes",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS"
            },{
                "sku_code":"UN-12322;28",
                "sku_desc":"Black Halterneck > Corset",
                "quantity":"10",
                "price":"200",
                "weight":"0.86",
                "length":"10",
                "width":"10",
                "height":"10",
                "dimensions_uom":"mm",
                "hs_code":"4331767",
                "country_code":"GB",
                "img_path":"https://intelligentreturns.net/assets/frontend/img/rebound_logo.png",
                "dangerous_goods":"No",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS"
            }
        ]
    }
}

XML

URL:
https://intelligentreturns.net/api/returns/create/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<return>
    <order_reference>12312355</order_reference>
    <service_id>1</service_id>
    <phone>+010557779</phone>
    <email>doe@gmail.com</email>
    <display_id>123123123</display_id>
    <name>John Doe</name>
    <country>US</country>
    <state>NY</state>
    <zip>12207</zip>
    <city>Albany</city>
    <addr1>City Hall</addr1>
    <addr2>24 Eagle Street, Room 102</addr2>
    <addr3></addr3>
    <final_dest_id>Default</final_dest_id>
    <final_dest_country>UK</final_dest_country>
    <final_dest_state>West Midlands</final_dest_state>
    <final_dest_zip>TF3 3BJ</final_dest_zip>
    <final_dest_city>Telford</final_dest_city>
    <final_dest_addr1>Telford Transport Solutions Ltd</final_dest_addr1>
    <final_dest_addr2>Stafford Park 12</final_dest_addr2>
    <final_dest_addr3></final_dest_addr3>
    <item>
        <sku_code>ASD111</sku_code>
        <sku_desc>Black Sculpting &amp; Smoothing Shapewear Body Suit-EUR 38 (M)</sku_desc>
        <quantity>5</quantity>
        <price>100</price>
        <weight>0.3</weight>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>5905954</hs_code>
        <country_code>CN</country_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>No</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
    </item>
    <item>
        <sku_code>UN-12322;28</sku_code>
        <sku_desc>Black Halterneck &gt; Corset</sku_desc>
        <quantity>10</quantity>
        <price>200</price>
        <weight>0.86</weight>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>4331767</hs_code>
        <country_code>GB</country_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>No</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
    </item>
</return>

Output data


Return created successfully:

{
    "success": {
        "label": "base64 from pdf label file",
        "tracking": "526u8we",
        "first_mile_address": {
            "addr1": "Telford Transport Solutions Ltd",
            "addr2": "Stafford Park 12",
            "city": "Telford",
            "zip": "TF3 3BJ",
            "state": "Shropshire",
            "country": "GB",
            "additional_address": []
        }
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<success>
    <label>base64 from pdf label file</label>
    <tracking>526u8we</tracking>
    <first_mile_address>
        <addr1>BTG c/o Laser Transport</addr1>
        <addr2>Flosshafenstrasse 10</addr2>
        <city>Neuss</city>
        <zip>41460</zip>
        <state>Neuss</state>
        <country>DE</country>
        <additional_address></additional_address>
    </first_mile_address>
</success>

Incorrect return data:

{
    "error": {
        "code": "return_invalid",
        "message": [
            "Field order_reference can not be empty."
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>return_invalid</code>
    <message>Field order_reference can not be empty.</message>
</error>

JSON is not valid:

{
    "error": {
        "code": "json_invalid",
        "message": [
            "JSON is not valid"
        ]
    }
}
        

XML is not valid:

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>xml_invalid</code>
    <message>XML is not valid</message>
</error>

Error codes

Error code Description
currency_code_invalid Invalid currency code
service_nx Requested carrier service does not exist
carrier_nx Requested carrier service does not exist
service_id_empty service_id field is empty
label_format_is_not_available Requested label format is not available for chosen carrier
incorrect_label_format Incorrect label format
return_invalid Return details (address, items) are invalid. See detailed description in error message
item_empty In case items data is required for customs
return_items_different_from_order Return items do not match ordered items. This error will appear only in case order data was provided
item_invalid Incorrect return item data. See detailed description in error message
collection_date_format Incorrect collection date format.
collection_date_time_from_format Incorrect collection date "time_from" format.
collection_date_time_to_format Incorrect collection date "time_to" format.
collection_time_error Incorrect collection time.
collection_date_error Incorrect collection date.
home_collection_is_unavailable Home collection service is unavailable for chosen carrier.
account_setup_required Current API user don't have required privileges to book a return on the provided address.
drop_off_point_not_found Selected drop-off point was not found.
no_shipping_services_available No services found. This error may occur if shipping services were not configured for your account or due to the parcel oversize/overweight.
shipping_method_unavailable Chosen carrier service is temporary unavailable.
external_api_error External API have responded with an error. See details in error message.
address_incorrect Sender address is incorrect.
enter_valid_email Sender email is incorrect.
enter_valid_phone Sender phone is incorrect.
zip_incorrect Sender zip code is incorrect.
state_incorrect Sender state code is incorrect.
order_reference_error Order reference is incorrect.

Input data


Return info

Key Type Value
id * string(255) Search will be performed using this value
type string(255) Indicates which field to search by.
  • id
  • order_reference
  • external_id
If the "type" field is ignored, then a search will be performed by "id", "order_reference", "external_id" fields at once and the earliest created record will be returned

You can provide a search data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/returns/get/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "return":
    {
        "id":"2901"
    }
}

XML

URL:
https://intelligentreturns.net/api/returns/get/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<return>
    <id>2901</id>
</return>

Output data


Data found:

If return was found, you will receive data in success field of JSON or XML format (depends on what format you've been requested).

Response fields. Return info.

Key Value
id ID of return
order_reference Order reference
date_added Unix timestamp of date when return was created.
phone Customer's phone
email Customer's email
display_id An additional information, which will be displayed on the shipping label (if it is possible). Order reference as default.
tracking Tracking code
tracking_last_update Unix timestamp of date when tracking status was updated.
current_tracking_status Digital code of current tracking status.
carrier Carrier name
label Base64 from pdf file with label
item Items of return. Can be empty.
verification_entity Boolean value. 1: true. 0: false

Address Info

Key Desc
name Customer full name (Person)
company_name Company name
country Customer's country code (ISO 3166-1 alpha-2)
state Customer's state
zip Zip/Post code
city City
suburb Suburb
addr1 Address line 1
addr2 Address line 2
addr3 Address line 3
neighborhood Neighborhood. Available only for Mexico
final_dest_name Final destination contact name
final_dest_company_name Final destination company name
final_dest_id Final destination address ID. Can be provided instead of full final destination address (fields below), in this case destination address fields will be ignored.
final_dest_country Final destination country code (ISO 3166-1 alpha-2)
final_dest_state Final destination State
final_dest_zip Final destination Zip/Post code
final_dest_city Final destination City
final_dest_suburb Final destination Suburb
final_dest_addr1 Final destination Address line 1
final_dest_addr2 Final destination Address line 2
final_dest_addr3 Final destination Address line 3
final_dest_neighborhood Final destination neighborhood. Available only for Mexico

Item info

Key Desc
sku_code Item SKU code
sku_desc Item SKU description
quantity Number of items sold
price Price of 1 item
weight Weight of 1 item. Default value: 1 (K/L).
weight_uom K / L (1 letter). Default value: K
length Length of 1 item
width Width of 1 item
height Height of 1 item
dimensions_uom cm, mm, in
country_code Country manufacturer code(2 letters)
hs_code Harmonization code
img_path Link to item image
dangerous_goods Possible values: Yes/No
tracking Tracking number for item
reason Reasons for item
reason/action Action
reason/reason Reason of return
reason/wish Wish
reason/additional Additional information
reason/additional/title Title of information
reason/additional/value value of information
export_date Export date
export_awb Export air waybill
export_carrier_name Exporter company
sku_url URL to assist in verification
final_dest_name Final destination contact name
final_dest_company_name Final destination company name
final_dest_id Final destination address ID. Can be provided instead of full final destination address (fields below), in this case destination address fields will be ignored.
final_dest_country Final destination country code (ISO 3166-1 alpha-2)
final_dest_state Final destination State
final_dest_zip Final destination Zip/Post code
final_dest_city Final destination City
final_dest_suburb Final destination Suburb
final_dest_addr1 Final destination Address line 1
final_dest_addr2 Final destination Address line 2
final_dest_addr3 Final destination Address line 3
final_dest_neighborhood Final destination neighborhood. Available only for Mexico
verification_entity Boolean value. 1: true. 0: false
final_disposition Can be 'return' or 'destroy'.

JSON response example:

{
    "success": {
        "id": "111495",
        "order_reference": "12312355",
        "date_added": "1465397894",
        "name": "John Doe",
        "zip": "12207",
        "email": "doe@gmail.com",
        "addr1": "City Hall",
        "addr2": "24 Eagle Street, Room 102",
        "addr3": "",
        "city": "Albany",
        "state": "NY",
        "country": "US",
        "phone": "+010557779",
        "tracking": "9202490112676104136413",
        "tracking_last_update": "1465397894",
        "current_tracking_status": "10",
        "final_dest_id": "Default",
        "final_dest_addr1": "Telford Transport Solutions Ltd",
        "final_dest_addr2": "Stafford Park 12",
        "final_dest_addr3": "",
        "final_dest_city": "Telford",
        "final_dest_zip": "TF3 3BJ",
        "final_dest_state": "West Midlands",
        "final_dest_country": "UK",
        "verification_entity": 0,
        "item": [
            {
                "sku_code": "ASD111",
                "sku_desc": "Black Sculpting Smoothing Shapewear Body Suit-EUR 38 (M)",
                "quantity": "2",
                "price": "100",
                "weight": "0.3",
                "weight_uom": "",
                "length": "",
                "width": "",
                "height": "",
                "dimensions_uom": "mm",
                "hs_code": "5905954",
                "country_code": "CN",
                "img_path": "",
                "dangerous_goods":"No",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS",
                "sku_url": "",
                "final_dest_name": "",
                "final_dest_company_name": "",
                "final_dest_id": "",
                "final_dest_country":"",
                "final_dest_state":"",
                "final_dest_zip":"",
                "final_dest_city":"",
                "final_dest_addr1":"",
                "final_dest_addr2":"",
                "final_dest_addr3":"",
                "final_dest_neighborhood":"",
                "verification_entity": 0,
                "final_disposition": "",
                "reason": [
                    {
                        "action": "Exchange",
                        "reason": "Too small",
                        "wish": "",
                        "additional": {
                            "title": "New size",
                            "value": "L"
                        }
                    },
                    {
                        "action": "Refund",
                        "reason": "Faulty",
                        "wish": "",
                        "additional": {
                            "title": "",
                            "value": ""
                        }
                    }
                ]
            },
            {
                "sku_code": "UN-12322;28",
                "sku_desc": "Black Halterneck Corset",
                "quantity": "1",
                "price": "200",
                "weight": "0.86",
                "weight_uom": "",
                "length": "",
                "width": "",
                "height": "",
                "dimensions_uom": "mm",
                "hs_code": "4331767",
                "country_code": "GB",
                "img_path": "",
                "dangerous_goods":"No",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS",
                "sku_url": "",
                "final_dest_name": "",
                "final_dest_company_name": "",
                "final_dest_id": "",
                "final_dest_country":"",
                "final_dest_state":"",
                "final_dest_zip":"",
                "final_dest_city":"",
                "final_dest_addr1":"",
                "final_dest_addr2":"",
                "final_dest_addr3":"",
                "final_dest_neighborhood":"",
                "verification_entity": 0,
                "final_disposition": "",
                "reason": [
                    {
                        "action": "Exchange",
                        "reason": "Too small",
                        "wish": "",
                        "additional": {
                            "title": "New size",
                            "value": "L"
                        }
                    }
                ]
            }
        ],
        "carrier": "ACP",
        "label": "base64 code from label"
    }
}
        

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <id>1227433</id>
    <order_reference>592edd0ef033e</order_reference>
    <date_added>1496243473</date_added>
    <name>John Doe</name>
    <company_name></company_name>
    <zip>12207</zip>
    <email>doe@gmail.com</email>
    <addr1>City Hall</addr1>
    <addr2>24 Eagle Street, Room 102</addr2>
    <addr3>Address line 3</addr3>
    <city>Albany</city>
    <state>NY</state>
    <country>US</country>
    <phone>+010557779</phone>
    <display_id>test display_id</display_id>
    <external_id></external_id>
    <final_dest_addr1>test final_dest_addr1</final_dest_addr1>
    <final_dest_addr2>test final_dest_addr2</final_dest_addr2>
    <final_dest_addr3>test final_dest_addr3</final_dest_addr3>
    <final_dest_city>test final_dest_city</final_dest_city>
    <final_dest_country>US</final_dest_country>
    <final_dest_state>test final_dest_state</final_dest_state>
    <final_dest_zip>test final_dest_zip</final_dest_zip>
    <final_dest_name></final_dest_name>
    <final_dest_company_name></final_dest_company_name>
    <final_dest_id></final_dest_id>
    <tracking>9202490112676107421264</tracking>
    <tracking_last_update>1496243476</tracking_last_update>
    <current_tracking_status>10</current_tracking_status>
    <verification_entity>0</verification_entity>
    <item>
        <sku_code>ASD111</sku_code>
        <sku_desc>Black Sculpting & Smoothing Shapewear Body Suit-EUR 38 (M)</sku_desc>
        <quantity>1</quantity>
        <price>100</price>
        <weight>0.3</weight>
        <weight_uom></weight_uom>
        <length></length>
        <width></width>
        <height></height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>5905954</hs_code>
        <country_code>CN</country_code>
        <img_path></img_path>
        <dangerous_goods>yes</dangerous_goods>
        <tracking></tracking>
        <export_date></export_date>
        <export_awb></export_awb>
        <export_carrier_name></export_carrier_name>
        <sku_url>sku_url-825470991</sku_url>
        <final_dest_name>final_dest_name-585022238</final_dest_name>
        <final_dest_company_name>final_dest_company_name-545265771</final_dest_company_name>
        <final_dest_id>final_dest_id-1404626025</final_dest_id>
        <final_dest_country>GB</final_dest_country>
        <final_dest_state>final_dest_state-1609489232</final_dest_state>
        <final_dest_zip>final_dest_zip-449086755</final_dest_zip>
        <final_dest_city>final_dest_city-39385187</final_dest_city>
        <final_dest_addr1>final_dest_add1-412216264</final_dest_addr1>
        <final_dest_addr2>final_dest_add2-565416059</final_dest_addr2>
        <final_dest_addr3>final_dest_add3-213443</final_dest_addr3>
        <final_dest_neighborhood>final_dest_neighborhood-438927438</final_dest_neighborhood>
        <verification_entity></verification_entity>
        <final_disposition>return</final_disposition>
        <reason>
            <action></action>
            <reason></reason>
            <wish></wish>
            <additional>
                <title></title>
                <value></value>
            </additional>
        </reason>
    </item>
    <item>
        <sku_code>UN-12322;28</sku_code>
        <sku_desc>Black Halterneck > Corset</sku_desc>
        <quantity>1</quantity>
        <price>200</price>
        <weight>0.86</weight>
        <weight_uom></weight_uom>
        <length></length>
        <width></width>
        <height></height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>4331767</hs_code>
        <country_code>GB</country_code>
        <img_path></img_path>
        <dangerous_goods>no</dangerous_goods>
        <tracking></tracking>
        <export_date></export_date>
        <export_awb></export_awb>
        <export_carrier_name></export_carrier_name>
        <sku_url>sku_url-1143217559</sku_url>
        <final_dest_name>final_dest_name-1105732117</final_dest_name>
        <final_dest_company_name>final_dest_company_name-397946632</final_dest_company_name>
        <final_dest_id>final_dest_id-1065831170</final_dest_id>
        <final_dest_country>UA</final_dest_country>
        <final_dest_state>final_dest_state-1311145863</final_dest_state>
        <final_dest_zip>final_dest_zip-1975861483</final_dest_zip>
        <final_dest_city>final_dest_city-1167678823</final_dest_city>
        <final_dest_addr1>final_dest_addr1-359905225</final_dest_addr1>
        <final_dest_addr2>final_dest_addr2-1327024868</final_dest_addr2>
        <final_dest_addr3>final_dest_addr3-311700808</final_dest_addr3>
        <final_dest_neighborhood>final_dest_neighborhood-1967127881</final_dest_neighborhood>
        <verification_entity></verification_entity>
        <final_disposition>destroy</final_disposition>
        <reason>
            <action></action>
            <reason></reason>
            <wish></wish>
            <additional>
                <title></title>
                <value></value>
            </additional>
        </reason>
    </item>
    <carrier>ACP</carrier>
    <label>base64 code from label</label>
</success>
        

Return not found:

{
    "error": {
        "code": "return_nx",
        "message": [
            "Return not found"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>return_nx</code>
    <message>Return not found</message>
</error>
        

Error codes

Error code Description
id_empty Field 'id' is required
incorrect_type Field 'type' has incorrect value
return_nx Return was not found
"Get returns by filters" method allows to get up to 1000 returns records, while "Get return" method will always find single record.
Please consider to use "Get return" if you need to get one record, as it will perform faster.

Input data


Filter data

Key Type Value
order_reference string(255) Order reference
date_from string | int Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
date_to string | int Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
quick_search string(255) Keywords divided by space. Each new keyword will narrow search results
status int Digital code for status of return. Available values:
  • 0 - Unprocessed
  • 1 - Delivered to Retailer
  • 2 - Declined
  • 3 - Has warnings
  • 5 - Refunded by Retailer
  • 4 - Delivery payment refunded
  • 900 - Processed on hub
  • 22 - On Quarantine
  • 23 - Removed from Quarantine
  • 32 - Return RMA verified
  • 33 - Return RMA verification failed
  • 300 - Return cancel requested
  • 301 - Return canceled by api method
  • 302 - Return canceled by email
  • 303 - Return canceled manually in interface
current_tracking_status int Digital code of current tracking status.
carrier string(255) Carrier name. Deprecated. Consider to use a "service_id" filter instead, in order to get more accurate results.
service_id int Service id
View list of all carrier services
country string(2) Customer's country code (ISO 3166-1 alpha-2)
id_last int Last ID from previous request.
You can get order by internal id or reference

You can provide an order data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/returns/items/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "filter":
    {
        "date_from":"10/15/2015",
        "date_to":"12/01/2015"
    }
}

XML

URL:
https://intelligentreturns.net/api/returns/items/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<filter>
    <date_from>10/15/2015</date_from>
    <date_to>12/01/2015</date_to>
</filter>

Output data


Data found:

If returns was found, you will receive data in success field of JSON or XML format (depends of what format you've been requested).
This method return maximum 1000 records. All returns are sorted by ID in descending order. If you need next page, use field id_last in filter.

Response fields. Return info.

Key Value
total The number of records that meet the filter.
return Data of returns. Description for fields of return you can see in Get return method.
* This method don't return label field.

JSON response example:

{
    "success": {
        "total": "2",
        "return": [
            {
                "id": "111495",
                "order_reference": "12312355",
                "date_added": "1465397894",
                "name": "John Doe",
                "zip": "12207",
                "email": "doe@gmail.com",
                "addr1": "City Hall",
                "addr2": "24 Eagle Street, Room 102",
                "addr3": "",
                "city": "Albany",
                "state": "NY",
                "country": "US",
                "phone": "+010557779",
                "tracking": "9202490112676104136413",
                "tracking_last_update": "1465397894",
                "current_tracking_status": "10",
                "verification_entity": 0,
                "item": [
                    {
                        "sku_code": "ASD111",
                        "sku_desc": "Black Sculpting Smoothing Shapewear Body Suit-EUR 38 (M)",
                        "quantity": "2",
                        "price": "100",
                        "weight": "0.3",
                        "weight_uom": "",
                        "length": "",
                        "width": "",
                        "height": "",
                        "dimensions_uom": "mm",
                        "hs_code": "5905954",
                        "country_code": "CN",
                        "img_path": "",
                        "dangerous_goods":"No",
                        "export_date": "946677600",
                        "export_awb": "32153454GB",
                        "export_carrier_name": "USPS",
                        "sku_url": "",
                        "final_dest_name": "",
                        "final_dest_company_name": "",
                        "final_dest_id": "",
                        "final_dest_country":"",
                        "final_dest_state":"",
                        "final_dest_zip":"",
                        "final_dest_city":"",
                        "final_dest_addr1":"",
                        "final_dest_addr2":"",
                        "final_dest_addr3":"",
                        "final_dest_neighborhood":"",
                        "verification_entity": 0,
                        "final_disposition": "",
                        "reason": [
                            {
                                "action": "Exchange",
                                "reason": "Too small",
                                "wish": "",
                                "additional": {
                                    "title": "New size",
                                    "value": "L"
                                }
                            },
                            {
                                "action": "Refund",
                                "reason": "Faulty",
                                "wish": "",
                                "additional": {
                                    "title": "",
                                    "value": ""
                                }
                            }
                        ]
                    },
                    {
                        "sku_code": "UN-12322;28",
                        "sku_desc": "Black Halterneck Corset",
                        "quantity": "1",
                        "price": "200",
                        "weight": "0.86",
                        "weight_uom": "",
                        "length": "",
                        "width": "",
                        "height": "",
                        "dimensions_uom": "mm",
                        "hs_code": "4331767",
                        "country_code": "GB",
                        "img_path": "",
                        "dangerous_goods":"No",
                        "export_date": "946677600",
                        "export_awb": "32153454GB",
                        "export_carrier_name": "USPS",
                        "sku_url": "",
                        "final_dest_name": "",
                        "final_dest_company_name": "",
                        "final_dest_id": "",
                        "final_dest_country":"",
                        "final_dest_state":"",
                        "final_dest_zip":"",
                        "final_dest_city":"",
                        "final_dest_addr1":"",
                        "final_dest_addr2":"",
                        "final_dest_addr3":"",
                        "final_dest_neighborhood":"",
                        "verification_entity": 0,
                        "final_disposition": "",
                        "reason": [
                            {
                                "action": "Exchange",
                                "reason": "Too small",
                                "wish": "",
                                "additional": {
                                    "title": "New size",
                                    "value": "L"
                                }
                            }
                        ]
                    }
                ],
                "carrier": "ACP"
            },
            {
                "id": "111494",
                "order_reference": "12312355",
                "date_added": "1465397745",
                "name": "John Doe",
                "zip": "12207",
                "email": "doe@gmail.com",
                "addr1": "City Hall",
                "addr2": "24 Eagle Street, Room 102",
                "city": "Albany",
                "state": "NY",
                "country": "US",
                "phone": "+010557779",
                "tracking": "9202490112676104136369",
                "tracking_last_update": "1465397745",
                "current_tracking_status": "10",
                "verification_entity": 0,
                "item": [
                    {
                        "sku_code": "ASD111",
                        "sku_desc": "Black Sculpting & Smoothing Shapewear Body Suit-EUR 38 (M)",
                        "quantity": "2",
                        "price": "100",
                        "weight": "0.3",
                        "weight_uom": "",
                        "length": "",
                        "width": "",
                        "height": "",
                        "dimensions_uom": "mm",
                        "hs_code": "5905954",
                        "country_code": "CN",
                        "img_path": "",
                        "dangerous_goods":"No",
                        "export_date": "946677600",
                        "export_awb": "32153454GB",
                        "export_carrier_name": "USPS",
                        "sku_url": "",
                        "final_dest_name": "",
                        "final_dest_company_name": "",
                        "final_dest_id": "",
                        "final_dest_country":"",
                        "final_dest_state":"",
                        "final_dest_zip":"",
                        "final_dest_city":"",
                        "final_dest_addr1":"",
                        "final_dest_addr2":"",
                        "final_dest_addr3":"",
                        "final_dest_neighborhood":"",
                        "verification_entity": 0,
                        "final_disposition": "",
                        "reason": [
                            {
                                "action": "Exchange",
                                "reason": "Too small",
                                "wish": "",
                                "additional": {
                                    "title": "New size",
                                    "value": "L"
                                }
                            },
                            {
                                "action": "Refund",
                                "reason": "Faulty",
                                "wish": "",
                                "additional": {
                                    "title": "",
                                    "value": ""
                                }
                            }
                        ]
                    },
                    {
                        "sku_code": "UN-12322;28",
                        "sku_desc": "Black Halterneck > Corset",
                        "quantity": "1",
                        "price": "200",
                        "weight": "0.86",
                        "weight_uom": "",
                        "length": "",
                        "width": "",
                        "height": "",
                        "dimensions_uom": "mm",
                        "hs_code": "4331767",
                        "country_code": "GB",
                        "img_path": "",
                        "dangerous_goods":"No",
                        "export_date": "946677600",
                        "export_awb": "32153454GB",
                        "export_carrier_name": "USPS",
                        "sku_url": "",
                        "final_dest_name": "",
                        "final_dest_company_name": "",
                        "final_dest_id": "",
                        "final_dest_country":"",
                        "final_dest_state":"",
                        "final_dest_zip":"",
                        "final_dest_city":"",
                        "final_dest_addr1":"",
                        "final_dest_addr2":"",
                        "final_dest_addr3":"",
                        "final_dest_neighborhood":"",
                        "verification_entity": 0,
                        "final_disposition": "",
                        "reason": [
                            {
                                "action": "Exchange",
                                "reason": "Too small",
                                "wish": "",
                                "additional": {
                                    "title": "New size",
                                    "value": "L"
                                }
                            }
                        ]
                    }
                ],
                "carrier": "ACP"
            }
        ]
    }
}
        

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <total>2</total>
    <return>
        <id>813253</id>
        <order_reference>246248138</order_reference>
        <date_added>1487634969</date_added>
        <name>GIANNAKOUDAKI EIRINI</name>
        <company_name></company_name>
        <zip>14569</zip>
        <email>eyannn@hotmail.com</email>
        <addr1>Amygdaleas 6A Aniksi</addr1>
        <addr2></addr2>
        <addr3></addr3>
        <city>Athens</city>
        <state>Aniksi</state>
        <country>GR</country>
        <phone></phone>
        <display_id>246248138</display_id>
        <external_id></external_id>
        <final_dest_addr1></final_dest_addr1>
        <final_dest_addr2></final_dest_addr2>
        <final_dest_addr3></final_dest_addr3>
        <final_dest_city></final_dest_city>
        <final_dest_country></final_dest_country>
        <final_dest_state></final_dest_state>
        <final_dest_zip></final_dest_zip>
        <final_dest_name></final_dest_name>
        <final_dest_company_name></final_dest_company_name>
        <final_dest_id></final_dest_id>
        <tracking>00340435014611159001</tracking>
        <tracking_last_update>1487634969</tracking_last_update>
        <current_tracking_status>10</current_tracking_status>
        <verification_entity>0</verification_entity>
        <item>
            <sku_code>ASD111</sku_code>
            <sku_desc>Black Sculpting Smoothing Shapewear Body Suit-EUR 38 (M)</sku_desc>
            <quantity>2</quantity>
            <price>100</price>
            <weight>0.3</weight>
            <weight_uom></weight_uom>
            <length></length>
            <width></width>
            <height></height>
            <dimensions_uom>mm</dimensions_uom>
            <hs_code>5905954</hs_code>
            <country_code>CN</country_code>
            <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
            <dangerous_goods>No</dangerous_goods>
            <export_date>946677600</export_date>
            <export_awb>32153454GB</export_awb>
            <export_carrier_name>USPS</export_carrier_name>
            <sku_url></sku_url>
            <final_dest_name></final_dest_name>
            <final_dest_company_name></final_dest_company_name>
            <final_dest_id></final_dest_id>
            <final_dest_country></final_dest_country>
            <final_dest_state></final_dest_state>
            <final_dest_zip></final_dest_zip>
            <final_dest_city></final_dest_city>
            <final_dest_addr1></final_dest_addr1>
            <final_dest_addr2></final_dest_addr2>
            <final_dest_addr3></final_dest_addr3>
            <final_dest_neighborhood></final_dest_neighborhood>
            <verification_entity>0</verification_entity>
            <final_disposition></final_disposition>
            <reason>
                <action>Exchange</action>
                <reason>Too small</reason>
                <wish></wish>
                <additional>
                    <title>New size</title>
                    <value>L</value>
                </additional>
            </reason>
            <reason>
                <action>Refund</action>
                <reason>Faulty</reason>
                <wish></wish>
                <additional>
                    <title></title>
                    <value></value>
                </additional>
            </reason>
        </item>
        <item>
            <sku_code>UN-12322;28</sku_code>
            <sku_desc>Black Halterneck Corset</sku_desc>
            <quantity>1</quantity>
            <price>200</price>
            <weight>0.86</weight>
            <weight_uom></weight_uom>
            <length></length>
            <width></width>
            <height></height>
            <dimensions_uom>mm</dimensions_uom>
            <hs_code>4331767</hs_code>
            <country_code>GB</country_code>
            <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
            <dangerous_goods>No</dangerous_goods>
            <export_date>946677600</export_date>
            <export_awb>32153454GB</export_awb>
            <export_carrier_name>USPS</export_carrier_name>
            <sku_url></sku_url>
            <final_dest_name></final_dest_name>
            <final_dest_company_name></final_dest_company_name>
            <final_dest_id></final_dest_id>
            <final_dest_country></final_dest_country>
            <final_dest_state></final_dest_state>
            <final_dest_zip></final_dest_zip>
            <final_dest_city></final_dest_city>
            <final_dest_addr1></final_dest_addr1>
            <final_dest_addr2></final_dest_addr2>
            <final_dest_addr3></final_dest_addr3>
            <final_dest_neighborhood></final_dest_neighborhood>
            <verification_entity>0</verification_entity>
            <final_disposition></final_disposition>
            <reason>
                <action>Exchange</action>
                <reason>Too small</reason>
                <wish></wish>
                <additional>
                    <title>New size</title>
                    <value>L</value>
                </additional>
            </reason>
        </item>
        <carrier>DHL</carrier>
    </return>
    <return>
        <id>813252</id>
        <order_reference>250483484</order_reference>
        <date_added>1487634904</date_added>
        <name>Dominika Stasiak</name>
        <company_name></company_name>
        <zip>62-800</zip>
        <email>chococat@hotmail.co.uk</email>
        <addr1>Legionow 24-26/27</addr1>
        <addr2></addr2>
        <addr3></addr3>
        <city>Kalisz</city>
        <state>Wielkopolska</state>
        <country>PL</country>
        <phone>0048514100805</phone>
        <display_id>250483484</display_id>
        <external_id></external_id>
        <final_dest_addr1></final_dest_addr1>
        <final_dest_addr2></final_dest_addr2>
        <final_dest_addr3></final_dest_addr3>
        <final_dest_city></final_dest_city>
        <final_dest_country></final_dest_country>
        <final_dest_state></final_dest_state>
        <final_dest_zip></final_dest_zip>
        <final_dest_name></final_dest_name>
        <final_dest_company_name></final_dest_company_name>
        <final_dest_id></final_dest_id>
        <tracking>514500212847</tracking>
        <tracking_last_update>1488412800</tracking_last_update>
        <current_tracking_status>60</current_tracking_status>
        <verification_entity>0</verification_entity>
        <item>
            <sku_code>ASD111</sku_code>
            <sku_desc>Black Sculpting &amp; Smoothing Shapewear Body Suit-EUR 38 (M)</sku_desc>
            <quantity>2</quantity>
            <price>100</price>
            <weight>0.3</weight>
            <weight_uom></weight_uom>
            <length></length>
            <width></width>
            <height></height>
            <dimensions_uom>mm</dimensions_uom>
            <hs_code>5905954</hs_code>
            <country_code>CN</country_code>
            <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
            <dangerous_goods>No</dangerous_goods>
            <export_date>946677600</export_date>
            <export_awb>32153454GB</export_awb>
            <export_carrier_name>USPS</export_carrier_name>
            <sku_url></sku_url>
            <final_dest_name></final_dest_name>
            <final_dest_company_name></final_dest_company_name>
            <final_dest_id></final_dest_id>
            <final_dest_country></final_dest_country>
            <final_dest_state></final_dest_state>
            <final_dest_zip></final_dest_zip>
            <final_dest_city></final_dest_city>
            <final_dest_addr1></final_dest_addr1>
            <final_dest_addr2></final_dest_addr2>
            <final_dest_addr3></final_dest_addr3>
            <final_dest_neighborhood></final_dest_neighborhood>
            <verification_entity>0</verification_entity>
            <final_disposition></final_disposition>
            <reason>
                <action>Exchange</action>
                <reason>Too small</reason>
                <wish></wish>
                <additional>
                    <title>New size</title>
                    <value>L</value>
                </additional>
            </reason>
            <reason>
                <action>Refund</action>
                <reason>Faulty</reason>
                <wish></wish>
                <additional>
                    <title></title>
                    <value></value>
                </additional>
            </reason>
        </item>
        <item>
            <sku_code>UN-12322;28</sku_code>
            <sku_desc>Black Halterneck &gt; Corset</sku_desc>
            <quantity>10</quantity>
            <price>200</price>
            <weight>0.86</weight>
            <weight_uom></weight_uom>
            <length></length>
            <width></width>
            <height></height>
            <dimensions_uom>mm</dimensions_uom>
            <hs_code>4331767</hs_code>
            <country_code>GB</country_code>
            <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
            <dangerous_goods>No</dangerous_goods>
            <export_date>946677600</export_date>
            <export_awb>32153454GB</export_awb>
            <export_carrier_name>USPS</export_carrier_name>
            <sku_url></sku_url>
            <final_dest_name></final_dest_name>
            <final_dest_company_name></final_dest_company_name>
            <final_dest_id></final_dest_id>
            <final_dest_country></final_dest_country>
            <final_dest_state></final_dest_state>
            <final_dest_zip></final_dest_zip>
            <final_dest_city></final_dest_city>
            <final_dest_addr1></final_dest_addr1>
            <final_dest_addr2></final_dest_addr2>
            <final_dest_addr3></final_dest_addr3>
            <final_dest_neighborhood></final_dest_neighborhood>
            <verification_entity>0</verification_entity>
            <final_disposition></final_disposition>
            <reason>
                <action>Exchange</action>
                <reason>Too small</reason>
                <wish></wish>
                <additional>
                    <title>New size</title>
                    <value>L</value>
                </additional>
            </reason>
        </item>
        <carrier>DHL</carrier>
    </return>
</success>
        

Return not found:

{
    "error": {
        "code": "return_nx",
        "message": [
            "Return not found"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>return_nx</code>
    <message>Return not found</message>
</error>
        

Error codes

Error code Description
quick_search_temporary_unavailable 'quick_search' option is temporary unavailable
temporary_unavailable Search method is temporary unavailable
return_nx No results found

Input data


Following method can be used for:
  • To retrieve pricing quotes and service coverage by providing a complete information of return
  • To retrieve only a service coverage. In this case, you can ignore a "Information of return" field set.
    Address and items information, however, remain mandatory.
Response format will be the same for both cases.

Information of return

Key Type Desc
order_reference string(255) Order reference
date_added string | int Return booking date, current time by default. Allowed date formats: mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp
tracking string(255) Tracking number.
Please, note! This field has to be provided if a return has been already booked/registered without using the Intelligentreturns software.
In this case, return will be saved and thereafter will receive tracking updates, but the booking process will be omitted.
-
Otherwise, omit this field or leave it blank, then a return will registered by the Intelligentreturns software and will acquire tracking number automatically.
currency_code string(3) Currency code(3 letters) ISO_4217. This indicates a currency in which the original order was placed.
phone string(255) Phone
email string(255) Email
display_id string(32) An additional information, which will be displayed on the shipping label (if it is possible). Max length 32 characters
Please note, that Hermes carrier limits display_id to 20 characters
external_id string(255) Alphanumeric value. Must be unique for each return. This field can be used in /returns/get/ method
add_items_data_to_order boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
Please, refer to the Create return section for detailed description.
export_date int Unix timestamp of export date. Default value, will be applied to all items, if not specified in corresponding item field
export_awb string(255) Export air waybill. Default value, will be applied to all items, if not specified in corresponding item field
export_carrier_name string(255) Exporter company. Default value, will be applied to all items, if not specified in corresponding item field
verification_entity boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
dangerous_goods string(255) Possible values: Yes/No. Default value, will be applied to all items, if not specified in corresponding item field
final_disposition string(255) Can be 'return' or 'destroy'. Default value, will be applied to all items, if not specified in corresponding item field
collection_address object Collection address is available only for home_collection service types.
If not specified, then origin address will be used instead
collection_address fields

Address Info

Key Type Desc
name string(255) Customer full name (Person)
company_name string(255) Company name
country * string(2) Customer's country code (ISO 3166-1 alpha-2)
state * string(255) Please, provide a state ISO code for a following countries:
  • AU
  • US
  • CA
Customer's state
Not required for following countries:
  • GB
  • UK
  • IL
  • DE
  • FR
  • NL
  • IE
  • SE
  • IT
  • DK
  • AT
  • LU
  • CZ
  • BE
  • BG
  • HR
  • CY
  • FI
  • GR
  • HU
  • MT
  • PL
  • PT
  • RO
  • SK
  • SI
  • EE
  • LV
  • LT
  • NZ
zip * string(255) Zip/Post code
Not required for following countries:
  • HK
  • IE
  • IL
city * string(255) City. Not mandatory for AU
suburb string(255) Suburb. Mandatory for AU
addr1 * string(255) Address line 1
addr2 string(255) Address line 2
addr3 string(255) Address line 3
neighborhood string(255) Neighborhood. Available only for Mexico
lat and lng fields can be provided instead of required address fields: country, city(suburb for AU), state, zip, addr1.
Address fields have a priority over coordinates(lat, lng) in case both are provided.
Either of the following sets must be provided:
  • country, city(suburb for AU), state, zip, addr1
  • lat, lng
lat double Latitude. Required if address was not provided
lng double Longitude. Required if address was not provided
final_dest_name string(255) Final destination contact name
final_dest_company_name string(255) Final destination company name
final_dest_id int Final destination address ID. Can be provided instead of full final destination address (fields below), in this case destination address fields will be ignored.
final_dest_country string(2) Final destination country code (ISO 3166-1 alpha-2)
final_dest_state string(255) Final destination State
final_dest_zip string(255) Final destination Zip/Post code
final_dest_city string(255) Final destination City
final_dest_suburb string(255) Final destination Suburb
final_dest_addr1 string(255) Final destination Address line 1
final_dest_addr2 string(255) Final destination Address line 2
final_dest_addr3 string(255) Final destination Address line 3
final_dest_neighborhood string(255) Final destination neighborhood. Available only for Mexico

Item info

Key Type Desc
sku_code * string(255) Item SKU code
sku_desc * string(255) Item SKU description
quantity * int Number of items sold
price * double Price of 1 item
weight double Weight of 1 item. Default value: 1 (K/L).
weight_uom string(1) K / L (1 letter). Default value: K
length double Length of 1 item
width double Width of 1 item
height double Height of 1 item
dimensions_uom string(2) cm, mm, in
country_code string(2) Country manufacturer code(2 letters)
hs_code string(255) Harmonization code
img_path string(255) Link to item image
dangerous_goods string(255) Possible values: Yes/No
export_date int Unix timestamp of export date
export_awb string(255) Export air waybill
export_carrier_name string(255) Exporter company
sku_url string(255) URL to assist in verification
final_dest_name string(255) Final destination contact name
final_dest_company_name string(255) Final destination company name
final_dest_id int Final destination address ID. Can be provided instead of full final destination address (fields below), in this case destination address fields will be ignored.
final_dest_country string(2) Final destination country code (ISO 3166-1 alpha-2)
final_dest_state string(255) Final destination State
final_dest_zip string(255) Final destination Zip/Post code
final_dest_city string(255) Final destination City
final_dest_suburb string(255) Final destination Suburb
final_dest_addr1 string(255) Final destination Address line 1
final_dest_addr2 string(255) Final destination Address line 2
final_dest_addr3 string(255) Final destination Address line 3
final_dest_neighborhood string(255) Final destination neighborhood. Available only for Mexico
verification_entity boolean Boolean value. TRUE: "1" or "true". FALSE(default): omit this field, "0" or "false".
final_disposition string(255) Can be 'return' or 'destroy'.

collection_address (Not required)

Key Type Desc
state * string(255) Collection address state.
Not required for following countries:
  • GB
  • UK
  • IL
  • DE
  • FR
  • NL
  • IE
  • SE
  • IT
  • DK
  • AT
  • LU
  • CZ
  • BE
  • BG
  • HR
  • CY
  • FI
  • GR
  • HU
  • MT
  • PL
  • PT
  • RO
  • SK
  • SI
  • EE
  • LV
  • LT
  • NZ
zip * string(255) Zip/Post code
city * string(255) City. Not mandatory for AU
suburb string(255) Suburb. Mandatory for AU
addr1 * string(255) Address line 1
addr2 string(255) Address line 2
addr3 string(255) Address line 3

You can provide data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/returns/request_for_prices/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "return":
    {
        "order_reference":"12312355",
        "name":"John Doe",
        "phone":"+010557779",
        "email":"doe@gmail.com",
        "addr1":"City Hall",
        "addr2":"24 Eagle Street, Room 102",
        "addr3":"",
        "city":"Albany",
        "zip":"12207",
        "state":"NY",
        "country":"US",
        "final_dest_id": "Default",
        "final_dest_addr1":"Telford Transport Solutions Ltd",
        "final_dest_addr2":"Stafford Park 12",
        "final_dest_addr3":"",
        "final_dest_city":"Telford",
        "final_dest_zip":"TF3 3BJ",
        "final_dest_state":"West Midlands",
        "final_dest_country":"UK",
        "currency_code":"USD",
        "item":[
            {
                "sku_code":"ASD111",
                "sku_desc":"Black Sculpting & Smoothing Shapewear Body Suit-EUR 38 (M)",
                "quantity":"5",
                "price":"100",
                "weight":"0.3",
                "length":"10",
                "width":"10",
                "height":"10",
                "dimensions_uom":"mm",
                "hs_code":"5905954",
                "country_code":"CN",
                "img_path":"https://intelligentreturns.net/assets/frontend/img/rebound_logo.png",
                "dangerous_goods":"No",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS"
            },{
                "sku_code":"UN-12322;28",
                "sku_desc":"Black Halterneck > Corset",
                "quantity":"10",
                "price":"200",
                "weight":"0.86",
                "length":"10",
                "width":"10",
                "height":"10",
                "dimensions_uom":"mm",
                "hs_code":"4331767",
                "country_code":"GB",
                "img_path":"https://intelligentreturns.net/assets/frontend/img/rebound_logo.png",
                "dangerous_goods":"Yes",
                "export_date": "946677600",
                "export_awb": "32153454GB",
                "export_carrier_name": "USPS"
            }
        ]
    }
}

XML

URL:
https://intelligentreturns.net/api/returns/request_for_prices/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<return>
    <order_reference>12312355</order_reference>
    <currency_code>USD</currency_code>
    <phone>+010557779</phone>
    <email>doe@gmail.com</email>
    <name>John Doe</name>
    <country>US</country>
    <state>NY</state>
    <zip>12207</zip>
    <city>Albany</city>
    <addr1>City Hall</addr1>
    <addr2>24 Eagle Street, Room 102</addr2>
    <addr3></addr3>
    <final_dest_id>Default</final_dest_id>
    <final_dest_country>UK</final_dest_country>
    <final_dest_state>West Midlands</final_dest_state>
    <final_dest_zip>TF3 3BJ</final_dest_zip>
    <final_dest_city>Telford</final_dest_city>
    <final_dest_addr1>Telford Transport Solutions Ltd</final_dest_addr1>
    <final_dest_addr2>Stafford Park 12</final_dest_addr2>
    <final_dest_addr3></final_dest_addr3>
    <item>
        <sku_code>ASD111</sku_code>
        <sku_desc>Black Sculpting &amp; Smoothing Shapewear Body Suit-EUR 38 (M)</sku_desc>
        <quantity>5</quantity>
        <price>100</price>
        <weight>0.3</weight>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>5905954</hs_code>
        <country_code>CN</country_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>Yes</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
    </item>
    <item>
        <sku_code>UN-12322;28</sku_code>
        <sku_desc>Black Halterneck &gt; Corset</sku_desc>
        <quantity>10</quantity>
        <price>200</price>
        <weight>0.86</weight>
        <length>10</length>
        <width>10</width>
        <height>10</height>
        <dimensions_uom>mm</dimensions_uom>
        <hs_code>4331767</hs_code>
        <country_code>GB</country_code>
        <img_path>https://intelligentreturns.net/assets/frontend/img/rebound_logo.png</img_path>
        <dangerous_goods>No</dangerous_goods>
        <export_date>946677600</export_date>
        <export_awb>32153454GB</export_awb>
        <export_carrier_name>USPS</export_carrier_name>
    </item>
</return>

Output data


Response fields.

Key Type Value
carrier string(255) Carrier Name
service string(255) Service type
service_id int Service ID
type string(255) Service type
description string(65535) Service description
max_weight string(65535) Max wetight description.
max_dim string(65535) Max dimensions description
avg_delivery_info string(65535) Delivery Info
first_mile_price string(255) First mile price with currency.
parcel_processing_price string(255) Parcel processing price with currency.
final_mile_price string(255) Final mile price with currency.
customs_price string(255) Customs price with currency.
government_duty_price string(255) Government duty price with currency.
collection_dates array of object | boolean Array of nearest collection dates. Available only for home collection services. False if unavailable.

collection_dates

Key Type Value
date string(10) Collection date in yyyy/mm/dd format.
time_from string(5) | boolean Collection "time from" in hh:mm format. False if unavailable.
time_to string(5) | boolean Collection "time to" in hh:mm format. False if unavailable.
minimum_interval int | boolean Minimum interval between time from and time to in hours. False if unavailable.

Successful request for prices:

{
   "success": {
      "result": [
         {
            "carrier": "asm",
            "service": "home_collection",
            "service_id": 16,
            "service_name": "Home Collection",
            "type": "home_collection",
            "description": "Your parcel will be collected from your preferred location on a date convenient for you.",
            "max_weight": "2kg",
            "max_dim": "L < 220cm",
            "avg_delivery_info": "10 days",
            "first_mile_price": "8.76 USD",
            "parcel_processing_price": "0 USD",
            "final_mile_price": "4.33 USD",
            "customs_price": "0 USD",
            "government_duty_price": "0 USD",
            "collection_dates": [
                {
                    "date": "2017/05/05",
                    "time_from": "08:00",
                    "time_to": "19:00",
                    "minimum_interval": 2
                },
                {
                    "date": "2017/05/06",
                    "time_from": "08:00",
                    "time_to": "19:00",
                    "minimum_interval": 2
                },
                {
                    "date": "2017/05/08",
                    "time_from": "08:00",
                    "time_to": "19:00",
                    "minimum_interval": 2
                },
                {
                    "date": "2017/05/09",
                    "time_from": "08:00",
                    "time_to": "19:00",
                    "minimum_interval": 2
                }
            ]
         }
      ]
   }
}
                    
<?xml version="1.0" encoding="UTF-8"?>
<success>
    <result>
        <carrier>ams</carrier>
        <service>home_collection</service>
        <service_id>16</service_id>
        <service_name>Home Collection</service_name>
        <type>home_collection</type>
        <description>Your parcel will be collected from your preferred location on a date convenient for you.</description>
        <max_weight>25kg</max_weight>
        <max_dim>L < 220cm</max_dim>
        <avg_delivery_info>10 days</avg_delivery_info>
        <first_mile_price>8.76 USD</first_mile_price>
        <parcel_processing_price>0 USD</parcel_processing_price>
        <final_mile_price>4.33 USD</final_mile_price>
        <customs_price>0 USD</customs_price>
        <government_duty_price>0 USD</government_duty_price>
        <collection_dates>
            <date>2017/05/05</date>
            <time_from>08:00</time_from>
            <time_to>19:00</time_to>
            <minimum_interval>2</minimum_interval>
        </collection_dates>
        <collection_dates>
            <date>2017/05/06</date>
            <time_from>08:00</time_from>
            <time_to>19:00</time_to>
            <minimum_interval>2</minimum_interval>
        </collection_dates>
        <collection_dates>
            <date>2017/05/08</date>
            <time_from>08:00</time_from>
            <time_to>19:00</time_to>
            <minimum_interval>2</minimum_interval>
        </collection_dates>
        <collection_dates>
            <date>2017/05/09</date>
            <time_from>08:00</time_from>
            <time_to>19:00</time_to>
            <minimum_interval>2</minimum_interval>
        </collection_dates>
    </result>
</success>

Incorrect return data:

{
    "error": {
        "code": "return_invalid",
        "message": [
            "Field order_reference cannot be empty."
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>return_invalid</code>
    <message>Field order_reference cannot be empty.</message>
</error>

JSON is not valid:

{
    "error": {
        "code": "json_invalid",
        "message": [
            "JSON is not valid"
        ]
    }
}
        

XML is not valid:

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>xml_invalid</code>
    <message>XML is not valid</message>
</error>

Error codes

Error code Description
address_or_coordinates_required Either address or coordinates are required
cannot_find_address_by_coordinates Cannot find address by coordinates
return_invalid Return details (address, items) are invalid. See detailed description in error message
currency_code_invalid Invalid currency code
items_empty Return items information is required
return_items_different_from_order Return items do not match ordered items. This error will appear only in case order data was provided
item_invalid Incorrect return item data. See detailed description in error message
account_setup_required Current API user don't have required privileges to book a return on the provided address
no_shipping_services_available No services found. This error may occur if shipping services were not configured for your account or due to the parcel oversize/overweight.
no_results_found No services found.

Input data


Return info

Key Type Value
external_id string(255) Unique ID, which can be populated using Create return method
tracking string(255) Tracking number
Either 'external_id' or 'tracking' is required. If both are provided, then a result must match both.

You can provide a return data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/returns/cancel/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "return":
    {
        "tracking":"00350559268103460351"
    }
}
                                    

XML

URL:
https://intelligentreturns.net/api/returns/cancel/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<return>
    <tracking>00350559268103460351</tracking>
</return>
                                    

Output data


Return cancel requested successfully:

{
   "success": {
      "result": {
         "message": "Return cancel requested",
         "tracking": "ZF858435144GB",
         "external_id": "",
         "status": "Return cancel requested"
      }
   }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<success>
   <result>
      <message>Return cancel requested</message>
      <tracking>ZF858435100GB</tracking>
      <external_id />
      <status>Return cancel requested</status>
   </result>
</success>
        

Return not found:

{
    "error": {
        "code": "return_nx",
        "message": [
            "Return not found"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>return_nx</code>
    <message>Return not found</message>
</error>

Error codes

Error code Description
external_id_or_tracking_required Missing required field 'external_id' or 'tracking'.
return_nx Return was not found

Input data


URL:
https://intelligentreturns.net/api/tracking/get
Request data:
Key Type Value
tracking * object Tracking request object

tracking

Key Type Value
code * string(255) Tracking code

You can provide a filter data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/tracking/get/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "tracking":
    {
        "code": "514500294005"
    }
}

XML

URL:
https://intelligentreturns.net/api/tracking/get/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<tracking>
    <code>514500294005</code>
</tracking>

Output data


Response fields. Full tracking data.

Key Value
dt Tracking event date in unix timestamp format.
status Digital code of current tracking status.
location Location. Contains: country, state, city. Please note, that it may be empty.
pallet_number Pallet tracking number. Empty if parcel has not been added to a pallet
source_country Country from which a parcel was consigned. (ISO 3166-1 alpha-2)
carrier_name Carrier name (E.G. DHL)
service_id Internal service id, which can be used to determine carrier's service
external_id Unique ID, which can be populated using Create return method

Location

Key Value
country Country code (ISO 3166-1 alpha-2)
state State
city City

JSON response example:

{
   "success": {
      "track": [
         {
            "dt": "1488469413",
            "status": "10",
            "location": {
               "country": "CZ",
               "state": "ČR",
               "city": "Praha"
            }
         },
         {
            "dt": "1488482100",
            "status": "20",
            "location": {
               "country": "CZ",
               "state": "",
               "city": ""
            }
         },
         {
            "dt": "1488526560",
            "status": "30",
            "location": {
               "country": "CZ",
               "state": "",
               "city": ""
            }
         },
         {
            "dt": "1488561000",
            "status": "30",
            "location": {
               "country": "DE",
               "state": "Radefeld",
               "city": ""
            }
         },
         {
            "dt": "1488566460",
            "status": "30",
            "location": {
               "country": "DE",
               "state": "Radefeld",
               "city": ""
            }
         },
         {
            "dt": "1488603900",
            "status": "30",
            "location": {
               "country": "DE",
               "state": "Börnicke",
               "city": ""
            }
         },
         {
            "dt": "1488603960",
            "status": "40",
            "location": {
               "country": "DE",
               "state": "Großbeeren",
               "city": ""
            }
         },
         {
            "dt": "1488758400",
            "status": "50",
            "location": {
               "country": "DE",
               "state": "",
               "city": ""
            }
         },
         {
            "dt": "1488758400",
            "status": "60",
            "location": {
               "country": "GB",
               "state": "Selby",
               "city": "Selby"
            }
         }
      ],
      "pallet_number": "1000",
      "source_country": "CZ",
      "carrier_name": "DHL",
      "service_id": "23",
      "external_id": "999"
   }
}
        

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
   <track>
      <dt>1488469413</dt>
      <status>10</status>
      <location>
         <country>CZ</country>
         <state>ČR</state>
         <city>Praha</city>
      </location>
   </track>
   <track>
      <dt>1488482100</dt>
      <status>20</status>
      <location>
         <country>CZ</country>
         <state />
         <city />
      </location>
   </track>
   <track>
      <dt>1488526560</dt>
      <status>30</status>
      <location>
         <country>CZ</country>
         <state />
         <city />
      </location>
   </track>
   <track>
      <dt>1488561000</dt>
      <status>30</status>
      <location>
         <country>DE</country>
         <state>Radefeld</state>
         <city />
      </location>
   </track>
   <track>
      <dt>1488566460</dt>
      <status>30</status>
      <location>
         <country>DE</country>
         <state>Radefeld</state>
         <city />
      </location>
   </track>
   <track>
      <dt>1488603900</dt>
      <status>30</status>
      <location>
         <country>DE</country>
         <state>Börnicke</state>
         <city />
      </location>
   </track>
   <track>
      <dt>1488603960</dt>
      <status>40</status>
      <location>
         <country>DE</country>
         <state>Großbeeren</state>
         <city />
      </location>
   </track>
   <track>
      <dt>1488758400</dt>
      <status>50</status>
      <location>
         <country>DE</country>
         <state />
         <city />
      </location>
   </track>
   <track>
      <dt>1488758400</dt>
      <status>60</status>
      <location>
         <country>GB</country>
         <state>Selby</state>
         <city>Selby</city>
      </location>
   </track>
   <pallet_number>1000</pallet_number>
   <source_country>CZ</source_country>
   <carrier_name>DHL</carrier_name>
   <service_id>23</service_id>
   <external_id>999</external_id>
</success>
        

Nothing found:

{
    "error": {
        "code": "empty",
        "message": [
            "Nothing found."
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>empty</code>
    <message>Nothing found.</message>
</error>
                                

Error codes

Error code Description
code_empty Field 'code' is required
empty No tracking events was found

Input data


URL:
https://intelligentreturns.net/api/tracking/get_by_date_range
Filter data:
Key Type Value
date_from * string | int mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp
date_to * string | int mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp
source_country string(2) Country from which a parcel was consigned. (ISO 3166-1 alpha-2)

You can provide a filter data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/tracking/get_by_date_range/json
POST:
Key Value
login your login
api_key your API key
request JSON example.
Always apply urlencode to json data!
{
    "filter":
    {
        "date_from": "2017/10/23 00:10:49",
        "date_to": "2017/10/24 00:10:49"
    }
}

XML

URL:
https://intelligentreturns.net/api/tracking/get_by_date_range/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<filter>
    <date_from>2017/10/23 00:10:49</date_from>
    <date_to>2017/10/24 00:10:49</date_to>
</filter>

Output data


Please note, this method allows to get up to 20000 events. Make sure that a date range provided is not too wide.

Response fields. Tracking events grouped by tracking numbers.

Key Value
tracking_number Tracking number
pallet_number Pallet tracking number. Empty if parcel has not been added to a pallet
source_country Country from which a parcel was consigned. (ISO 3166-1 alpha-2)
carrier_name Carrier name (E.G. DHL)
service_id Internal service id, which can be used to determine carrier's service
external_id Unique ID, which can be populated using Create return method
events Tracking events. Contains: status, dt, location

Events

Key Value
status Digital code of current tracking status.
dt Tracking event date in unix timestamp format.
location Location. Contains: country, state, city. Please note, that it may be empty.

Location

Key Value
country Country code (ISO 3166-1 alpha-2)
state State
city City

JSON response example:

{
   "success": {
      "tracking_data": [
         {
            "tracking_number": "00350559268102004358",
            "pallet_number": "",
            "source_country": "SE",
            "carrier_name": "MyPack",
            "service_id": "40",
            "external_id": "",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Uppsala"
                  }
               },
               {
                  "status": "30",
                  "dt": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Uppsala"
                  }
               }
            ]
         },
         {
            "tracking_number": "00350559268102018270",
            "pallet_number": "",
            "source_country": "SE",
            "carrier_name": "MyPack",
            "service_id": "40",
            "external_id": "",
            "events": [
               {
                  "status": "30",
                  "dt": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Landvetter"
                  }
               }
            ]
         },
         {
            "tracking_number": "00350559268102009469",
            "pallet_number": "",
            "source_country": "SE",
            "carrier_name": "MyPack",
            "service_id": "40",
            "external_id": "",
            "events": [
               {
                  "status": "30",
                  "dt": "1475087940",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Järfälla"
                  }
               }
            ]
         },
         {
            "tracking_number": "512902293586",
            "pallet_number": "",
            "source_country": "RO",
            "carrier_name": "DHL",
            "service_id": "31",
            "external_id": "",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087940",
                  "location": {
                     "country": "RO",
                     "state": "",
                     "city": ""
                  }
               }
            ]
         },
         {
            "tracking_number": "00350559268102026343",
            "pallet_number": "",
            "source_country": "SE",
            "carrier_name": "MyPack",
            "service_id": "40",
            "external_id": "",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087940",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Stockholm"
                  }
               },
               {
                  "status": "30",
                  "dt": "1475087940",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Stockholm"
                  }
               }
            ]
         }
      ]
   }
}
        

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
   <tracking_data>
      <tracking_number>00350559268102004358</tracking_number>
      <pallet_number />
      <source_country>SE</source_country>
      <carrier_name>MyPack</carrier_name>
      <service_id>40</service_id>
      <external_id />
      <events>
         <status>20</status>
         <dt>1475087880</dt>
         <location>
            <country>SE</country>
            <state />
            <city>Uppsala</city>
         </location>
      </events>
      <events>
         <status>30</status>
         <dt>1475087880</dt>
         <location>
            <country>SE</country>
            <state />
            <city>Uppsala</city>
         </location>
      </events>
   </tracking_data>
   <tracking_data>
      <tracking_number>00350559268102018270</tracking_number>
      <pallet_number />
      <source_country>SE</source_country>
      <carrier_name>MyPack</carrier_name>
      <service_id>40</service_id>
      <external_id />
      <events>
         <status>30</status>
         <dt>1475087880</dt>
         <location>
            <country>SE</country>
            <state />
            <city>Landvetter</city>
         </location>
      </events>
   </tracking_data>
   <tracking_data>
      <tracking_number>00350559268102009469</tracking_number>
      <pallet_number />
      <source_country>SE</source_country>
      <carrier_name>MyPack</carrier_name>
      <service_id>40</service_id>
      <external_id />
      <events>
         <status>30</status>
         <dt>1475087940</dt>
         <location>
            <country>SE</country>
            <state />
            <city>Järfälla</city>
         </location>
      </events>
   </tracking_data>
   <tracking_data>
      <tracking_number>512902293586</tracking_number>
      <pallet_number />
      <source_country>RO</source_country>
      <carrier_name>DHL</carrier_name>
      <service_id>31</service_id>
      <external_id />
      <events>
         <status>20</status>
         <dt>1475087940</dt>
         <location>
            <country>RO</country>
            <state />
            <city />
         </location>
      </events>
   </tracking_data>
   <tracking_data>
      <tracking_number>00350559268102026343</tracking_number>
      <pallet_number />
      <source_country>SE</source_country>
      <carrier_name>MyPack</carrier_name>
      <service_id>40</service_id>
      <external_id />
      <events>
         <status>20</status>
         <dt>1475087940</dt>
         <location>
            <country>SE</country>
            <state />
            <city>Stockholm</city>
         </location>
      </events>
      <events>
         <status>30</status>
         <dt>1475087940</dt>
         <location>
            <country>SE</country>
            <state />
            <city>Stockholm</city>
         </location>
      </events>
   </tracking_data>
</success>
        

Nothing found:

{
    "error": {
        "code": "empty",
        "message": [
            "Nothing found."
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>empty</code>
    <message>Nothing found.</message>
</error>
                                

Error codes

Error code Description
date_filter_is_missing Date range is incorrect. See detailed description in error message
empty No tracking events was found

Input data


URL:
https://intelligentreturns.net/api/check/available
POST request body will be ignored and may be passed empty. No authorization required

You can receive a response in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/check/available/json

XML

URL:
https://intelligentreturns.net/api/check/available/xml

Output data


Response fields.

Key Value
date Server datetime in unix timestamp format.

JSON SUCCESS response example:

{
    "success": {
        "date": "1474467743"
    }
}
        

XML SUCCESS response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <date>
        1474467743
    </date>
</success>
        

JSON UNAVAILABLE response example:

{
   "error": {
      "code": "internal",
      "message": [
         "Internal server error."
      ]
   }
}
        

XML UNAVAILABLE response example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
   <code>internal</code>
   <message>Internal server error.</message>
</error>
        

Input data


URL:
https://intelligentreturns.net/api/services/get_available

Request data (* required)

Either 'country' or 'lat' and 'lng' fields are required
Key Type Value
country * string(2) Country code (ISO 3166-1 alpha-2)
state (Preferred) string(255) State/County
zip (Preferred) string(255) Zip/Post code
city (Preferred) string(255) City
suburb (Preferred for AU) string(255) Suburb
addr1 (Preferred) string(255) Address line 1
addr2 string(255) Address line 2
lat * double Latitude
lng * double Longitude

You can provide a request data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/services/get_available/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "request": {
        "country":"AU"
    }
}

XML

URL:
https://intelligentreturns.net/api/services/get_available/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<?xml version="1.0" encoding="UTF-8"?>
<request>
   <country>AU</country>
</request>

Output data


Response data

Key Type Value
success object Success response object

success

Key Type Value
services array of object Array of carrier objects

services

Key Type Value
carrier string(255) Carrier name
service_id int Carrier Service ID
service_name string(255) Carrier service name
coverage object Carrier service coverage. Includes coverage by country/state/city.

coverage

Key Type Value
countries array of object Array of countries that cover carrier service.

countries

Key Type Value
country string(2) Country code (ISO 3166-1 alpha-2)
states array of object | string(4) Array of states in case not all states in a country are covered. Otherwise string(4) "full".

states

Key Type Value
state string(255) State name or code (Codes only for: US, CA, AU)
cities array of string(255) | string(255) Array of cities in case not all cities are covered in a state. Otherwise string(4) "full".
suburbs array of string(255) | string(255) Array of suburbs in case not all suburbs are covered in a state. Otherwise string(4) "full".
Available only for Australia

JSON response example:

{
   "success": {
      "services": [
         {
            "carrier": "Temando",
            "service_id": "10",
            "service_name": "Couriers Please",
            "service_type": "home_collection",
            "coverage": {
               "countries": [
                  {
                     "country": "AU",
                     "states": "full"
                  }
               ]
            }
         },
         {
            "carrier": "Temando",
            "service_id": "11",
            "service_name": "Australia Post",
            "service_type": "drop_off",
            "coverage": {
               "countries": [
                  {
                     "country": "AU",
                     "states": [
                        {
                           "state": "act",
                           "cities": "full",
                           "suburbs": [
                              "acton",
                              "ainslie",
                              "amaroo"
                           ]
                        },
                        {
                           "state": "nsw",
                           "cities": "full",
                           "suburbs": "full"
                        },
                        {
                           "state": "nt",
                           "cities": "full",
                           "suburbs": "full"
                        }
                     ]
                  }
               ]
            }
         }
      ]
   }
}
        

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
   <services>
      <carrier>Temando</carrier>
      <service_id>10</service_id>
      <service_name>Couriers Please</service_name>
      <service_type>home_collection</service_type>
      <coverage>
         <countries>
            <country>AU</country>
            <states>full</states>
         </countries>
      </coverage>
   </services>
   <services>
      <carrier>Temando</carrier>
      <service_id>11</service_id>
      <service_name>Australia Post</service_name>
      <service_type>drop_off</service_type>
      <coverage>
         <countries>
            <country>AU</country>
            <states>
               <state>act</state>
               <cities>full</cities>
               <suburbs>acton</suburbs>
               <suburbs>ainslie</suburbs>
               <suburbs>amaroo</suburbs>
            </states>
            <states>
               <state>nsw</state>
               <cities>full</cities>
               <suburbs>full</suburbs>
            </states>
            <states>
               <state>nt</state>
               <cities>full</cities>
               <suburbs>full</suburbs>
            </states>
         </countries>
      </coverage>
   </services>
</success>
                                

Nothing found:

{
   "error": {
      "code": "service_nx",
      "message": [
         "No services were found by given address"
      ]
   }
}
                                
<?xml version="1.0" encoding="UTF-8"?>
<error>
   <code>service_nx</code>
   <message>No services were found by given address</message>
</error>
                                

Error codes

Error code Description
cannot_find_address_by_coordinates Cannot find address by coordinates
service_not_found No carrier services found
country_incorrect Incorrect country code

Input data


URL:
https://intelligentreturns.net/api/services/get_drop_off_points

Request data (* required)

Key Type Value
address object Address, which will be used to find nearest drop-off points.
Address has a priority over coordinates in case both are provided.
Please, find fields description below
Mandatory if coordinates empty
coordinates object Coordinates, which will be used to find nearest drop-off points
Please, find fields description below
Mandatory if address empty
services array of int Array of service IDs
radius int Search radius in km (kilometers)

Address info

Key Type Value
country * string(2) Country code (ISO 3166-1 alpha-2)
state string(255) State/County
Required for Hong Kong
zip (Preferred) string(255) Zip/Post code
city (Preferred) string(255) City
suburb (Preferred for AU) string(255) Suburb
addr1 (Preferred) string(255) Address line 1
addr2 string(255) Address line 2

Coordinates

Key Type Value
lat * double Latitude
lng * double Longitude

You can provide a request data in 2 formats: JSON, XML

JSON

URL:
https://intelligentreturns.net/api/services/get_drop_off_points/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "request": {
        "services": [
            1,
            2
        ],
        "address": {
            "country": "CA",
            "state": "ON",
            "zip": "M6H 2X5",
            "city": "Toronto",
            "addr1": "926 Dovercourt Rd",
            "addr2": ""
        },
        "coordinates": {
            "lat": "43.6657253",
            "lng": "-79.4313081"
        },
        "radius": "10"
    }
}

XML

URL:
https://intelligentreturns.net/api/services/get_drop_off_points/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<request>
    <services>1</services>
    <services>2</services>
    <address>
        <country>CA</country>
        <state>ON</state>
        <zip>M6H 2X5</zip>
        <city>Toronto</city>
        <addr1>926 Dovercourt Rd</addr1>
        <addr2></addr2>
    </address>
    <coordinates>
        <lat>43.6657253</lat>
        <lng>-79.4313081</lng>
    </coordinates>
    <radius>10</radius>
</request>

Output data


Response data

Key Type Value
success object Success response object

success

Key Type Value
carriers array of object Array of carrier objects

carriers

Key Type Value
id int Carrier id
name string(255) Carrier name
services array of object Array of service objects

services

Key Type Value
id int Service id. You can use this id for create return
name string(255) Service name
points array of object Array of drop off point objects

points

Key Type Value
id string(255) Drop off point id
title string(255) Drop off point title
address_detail object Object of drop off point detail address
hours string(255) | boolean Work hours of drop off point or false if not available
detail_hours object | boolean Object of formatted work hours or false if not available
lat double Latitude
lng double Longitude

address_detail

Key Type Value
country string(2) Country code (ISO 3166-1 alpha-2)
state string(255) State/County
zip string(255) Zip/Post code
city string(255) City
suburb string(255) Suburb
addr1 string(255) Address line 1
addr2 string(255) Address line 2

detail_hours

Key Type Value
mo array of string | boolean Array of monday work hours or false if not available
tu array of string | boolean Array of tuesday work hours or false if not available
we array of string | boolean Array of wednesday work hours or false if not available
th array of string | boolean Array of thursday work hours or false if not available
fr array of string | boolean Array of friday work hours or false if not available
sa array of string | boolean Array of saturday work hours or false if not available
su array of string | boolean Array of sunday work hours or false if not available

JSON response example:

{
    "success": {
        "carriers": [
            {
                "id": 4,
                "name": "Correos",
                "services": [
                    {
                        "id": 13,
                        "name": "Correos Drop Off",
                        "points": [
                            {
                                "id": "123ABC",
                                "title": "BARCELONA SUC 23. LES CORTS",
                                "address_detail": {
                                    "country": "ES",
                                    "state": "",
                                    "zip": "08028",
                                    "city": "BARCELONA",
                                    "addr1": "AV. MADRID 106",
                                    "addr2": ""
                                },
                                "hours": false,
                                "detail_hours": false,
                                "lat": "41.37881",
                                "lng": "2.1280565"
                            }
                        ]
                    }
                ]
            },
            {
                "id": 21,
                "name": "Hermes Europe",
                "services": [
                    {
                        "id": 48,
                        "name": "Hermes Parcel Shop",
                        "points": [
                            {
                                "id": "124ABC",
                                "title": "ELECTRODOMESTICOS PEINADO",
                                "address_detail": {
                                    "country": "ES",
                                    "state": "",
                                    "zip": "08028",
                                    "city": "BARCELONA",
                                    "addr1": "CL JOAN GUELL",
                                    "addr2": ""
                                },
                                "hours": "monday-saturday 10:00-14:00 monday-friday 17:00-20:30",
                                "detail_hours": {
                                    "mo": [
                                        "10:00-14:00",
                                        "17:00-20:30"
                                    ],
                                    "tu": [
                                        "10:00-14:00",
                                        "17:00-20:30"
                                    ],
                                    "we": [
                                        "10:00-14:00",
                                        "17:00-20:30"
                                    ],
                                    "th": [
                                        "10:00-14:00",
                                        "17:00-20:30"
                                    ],
                                    "fr": [
                                        "10:00-14:00",
                                        "17:00-20:30"
                                    ],
                                    "sa": [
                                        "10:00-14:00"
                                    ],
                                    "su": false
                                },
                                "lat": 41.382355,
                                "lng": 2.131578
                            },
                            {
                                "id": "125ABC",
                                "title": "BITPHONE",
                                "address_detail": {
                                    "country": "ES",
                                    "state": "",
                                    "zip": "08028",
                                    "city": "BARCELONA",
                                    "addr1": "CL GALILEO",
                                    "addr2": ""
                                },
                                "hours": "monday-friday 09:00-21:00 saturday 09:00-17:00",
                                "detail_hours": {
                                    "mo": [
                                        "09:00-21:00"
                                    ],
                                    "tu": [
                                        "09:00-21:00"
                                    ],
                                    "we": [
                                        "09:00-21:00"
                                    ],
                                    "th": [
                                        "09:00-21:00"
                                    ],
                                    "fr": [
                                        "09:00-21:00"
                                    ],
                                    "sa": [
                                        "09:00-17:00"
                                    ],
                                    "su": false
                                },
                                "lat": 41.3766,
                                "lng": 2.1356463
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
        

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <carriers>
        <id>4</id>
        <name>Correos</name>
        <services>
            <id>13</id>
            <name>Correos Drop Off</name>
            <points>
                <id>123ABC</id>
                <title>BARCELONA SUC 23. LES CORTS</title>
                <address_detail>
                    <country>ES</country>
                    <state></state>
                    <zip>08028</zip>
                    <city>BARCELONA</city>
                    <addr1>AV. MADRID 106</addr1>
                    <addr2></addr2>
                </address_detail>
                <hours></hours>
                <detail_hours></detail_hours>
                <lat>41.37881</lat>
                <lng>2.1280565</lng>
            </points>
        </services>
    </carriers>
    <carriers>
        <id>21</id>
        <name>Hermes Europe</name>
        <services>
            <id>48</id>
            <name>Hermes Parcel Shop</name>
            <points>
                <id>124ABC</id>
                <title>ELECTRODOMESTICOS PEINADO</title>
                <address_detail>
                    <country>ES</country>
                    <state></state>
                    <zip>08028</zip>
                    <city>BARCELONA</city>
                    <addr1>CL JOAN GUELL</addr1>
                    <addr2></addr2>
                </address_detail>
                <hours>monday-saturday 10:00-14:00 monday-friday 17:00-20:30</hours>
                <detail_hours>
                    <mo>10:00-14:00</mo>
                    <mo>17:00-20:30</mo>
                    <tu>10:00-14:00</tu>
                    <tu>17:00-20:30</tu>
                    <we>10:00-14:00</we>
                    <we>17:00-20:30</we>
                    <th>10:00-14:00</th>
                    <th>17:00-20:30</th>
                    <fr>10:00-14:00</fr>
                    <fr>17:00-20:30</fr>
                    <sa>10:00-14:00</sa>
                    <su></su>
                </detail_hours>
                <lat>41.382355</lat>
                <lng>2.131578</lng>
            </points>
            <points>
                <id>125ABC</id>
                <title>BITPHONE</title>
                <address_detail>
                    <country>ES</country>
                    <state></state>
                    <zip>08028</zip>
                    <city>BARCELONA</city>
                    <addr1>CL GALILEO</addr1>
                    <addr2></addr2>
                </address_detail>
                <hours>monday-friday 09:00-21:00 saturday 09:00-17:00</hours>
                <detail_hours>
                    <mo>09:00-21:00</mo>
                    <tu>09:00-21:00</tu>
                    <we>09:00-21:00</we>
                    <th>09:00-21:00</th>
                    <fr>09:00-21:00</fr>
                    <sa>09:00-17:00</sa>
                    <su></su>
                </detail_hours>
                <lat>41.3766</lat>
                <lng>2.1356463</lng>
            </points>
        </services>
    </carriers>
</success>
        

Nothing found:

{
    "error": {
        "code": "carrier_empty",
        "message": [
            "Missing required field 'address->country'."
        ]
    }
}
                                
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>carrier_empty</code>
    <message>Missing required field 'address->country'.</message>
</error>
                                

Error codes

Error code Description
location_empty Either 'address' or 'coordinates' field is required
lat_empty In case 'coordinates' field is present, 'lat' field is required
lng_empty In case 'coordinates' field is present, 'lng' field is required
cannot_find_address_by_coordinates Cannot find address by coordinates
service_not_found No carrier services found
country_incorrect Incorrect country code
no_drop_off_points_found No drop-off points found

Input data


Code Description
10 Return registered online
20 Received by the carrier
30 In transit to our local hub
40 Received at our local hub
43 Processed by hub
45 Parcel has been added to pallet
90 Parcel has been extracted from pallet
50 In transit to the retailer
60 Delivered to the retailer
70 Parcel refunded by retailer
100 Parcel delayed
110 Parcel lost
200 Parcel under investigation
120 Collection attempt failed
300 Cancel requested
201 Awaiting customs clearance
202 Customs clearance completed
310 Canceled

Output data


A list of all possible tracking status codes.

"Create order" request example.


<?php

$login = 'demo_api';
$api_key = 'api_key';

$order = array (
    'order_reference' => '1000000000000',
    'order_date' => '10/20/2015',
    'rma' => '12345',
    'contact_name' => 'John Smith',
    'company_name' => '',
    'addr1' => '6 Semaphore Close Mount Pleasant',
    'addr2' => '',
    'addr3' => 'Christchurch',
    'zip' => '8081',
    'state' => 'qwe',
    'country' => 'NZ',
    'phone' => '+102030405060',
    'email' => 'john.smith@googlemail.com',
    'currency_code' => 'AUD',
    'export_awb' => '32153454GB',
    'export_carrier_name' => 'USPS',
    'item' => array (
        array (
            'sku_code' => 'QWE123',
            'sku_desc' => 'Black Sculpting & Smoothing Shapewear Body Suit-EUR 38 (M)',
            'quantity' => '5',
            'price' => '100',
            'weight' => '1',
            'length' => '2',
            'width' => '3',
            'height' => '4',
            'dimensions_uom' => 'mm',
            'hs_code' => '',
            'country_code' => 'GB',
            'img_path' => '',
        ),
        array (
            'sku_code' => 'QWE456',
            'sku_desc' => 'Black Halterneck Corset',
            'quantity' => '10',
            'price' => '200',
            'weight' => '0.86',
            'length' => '0',
            'width' => '0',
            'height' => '0',
            'dimensions_uom' => 'mm',
            'hs_code' => '',
            'country_code' => 'GB',
            'img_path' => '',
        ),
    ),
);

// Production API entry point
$entryPoint = 'https://intelligentreturns.net/api/';
// Test API entry point
$entryPoint = 'http://test.intelligentreturns.net/api/';
$method = 'orders/create/';
$format = 'json';

$post = array(
    'login' => $login,
    'api_key' => $api_key,
    'request' => json_encode(array('order' => $order))
);

$ch = curl_init($entryPoint . $method . $format);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post, '', '&'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = curl_exec($ch);
if ($result === false) {
    // cURL error
    die(curl_error($ch));
}
curl_close($ch);

$response = json_decode($result, true);

if ($response === null) {
    // Not json response
    die($result);
}

if (!empty($response['success'])) {
    // Order created
    $order_id = $response['success']['order_id'];
    die('Ok. Order ID: '. $order_id);
} elseif (!empty($response['error'])) {
    // Order was not created
    $error_code = $response['error']['code'];
    $messages = $response['error']['message'];
    die('Error code: ' . $error_code. '. Messages: '.implode("\r\n", $messages));
}

die('Unknown response format.');

                                

"Check availability" method example.


<?php
// Production API entry point
$entryPoint = 'https://intelligentreturns.net/api/';
// Test API entry point
$entryPoint = 'http://test.intelligentreturns.net/api/';
$method = 'check/available/';
$format = 'json';

$post = array(
   'request' => ''
);

$ch = curl_init($entryPoint . $method . $format);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post, '', '&'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);

$result = curl_exec($ch);
if ($result === false) {
    // cURL error
    die(curl_error($ch));
}
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code != 200) {
    die('Temporary unavailable');
}

$response = json_decode($result, true);

if ($response === null) {
    // Not json response, check your request
    die($result);
}

if (!empty($response['success'])) {
    if(!empty($response['success']['date'])) {
        die('Ok. Service is available.');
    } else {
        // Check the online documentation https://intelligentreturns.net/api/
        var_dump($response);
        die('Unknown response format.');
    }
} elseif (!empty($response['error'])) {
    // Temporary unavailable
    $error_code = $response['error']['code'];
    $messages = $response['error']['message'];
    die('Error code: ' . $error_code. '. Messages: '.implode("\r\n", $messages));
}
// Check the online documentation https://intelligentreturns.net/api/
var_dump($response);
die('Unknown response format.');

                                
service_id Carrier name Service name Is trackable
1 ACP USPS Ground Service Yes
2 ACP USPS Priority Yes
3 Canada Post Canada Post Tracked Return Yes
4 InPost Canada InPost Parcel Locker Return Yes
5 Royal Mail Tracked Returns 48 Yes
6 Hermes UK Home Collection Yes
8 Hermes UK Hermes Parcel Shop Yes
9 PMP Pass my Parcel Mobile Yes
10 Temando Couriers Please Yes
11 Temando Australia Post Yes
12 Kiala Kiala Drop Off Point Yes
13 Correos Correos Drop Off Yes
14 Correos Correos Mobile Yes
15 AnPost AnPost Drop Off Yes
16 ASM Home Collection Yes
17 DHL Deutsche Post Tracked Parcel Yes
18 DHL Bpost Tracked Return Yes
19 DHL Eesti Post Tracked Return Yes
20 DHL Elta Tracked Return Yes
21 DHL Österreichische Post Tracked Parcel Yes
22 DHL Bulgarian Post Tracked Return Yes
23 DHL Ceska Posta Tracked Return Yes
24 DHL Cyprus Post Tracked Return Yes
25 DHL Colissimo Tracked Parcel Yes
26 DHL Magyar Posta Tracked Return Yes
27 DHL Poste Italiane Tracked Return Yes
28 DHL Latvijas Pasts Tracked Return Yes
29 DHL P&T Luxembourg Tracked Return Yes
30 DHL PostNL Tracked Return Yes
31 DHL Poşta Română Tracked Return Yes
32 DHL Slovenská Pošta Tracked Return Yes
33 DHL CTT Correios Tracked Parcel Yes
34 DHL Pošta Slovenije Tracked Return Yes
35 DHL Poczta Polska Tracked Return Yes
36 DHL Lietuvos Paštas Tracked Return Yes
37 DHL Posti Finland Tracked Return Yes
38 DHL Post Danmark Tracked Return Yes
39 DHL DHL Service Point Yes
40 MyPack MyPack Drop Off Yes
41 MyPack Pakke Drop Off Yes
42 Direct Link Untracked Return No
43 Self Post Self-Post Return No
44 Royale Parcel Shop Return Yes
45 CTT Correios Tracked Parcel Yes
46 Business Reply Royal Mail Business Reply Yes
47 nzpost Tracked Return Yes
48 Hermes Europe Hermes Parcel Shop Yes
49 Bring Posti Tracked Parcel Yes
50 Bring Tracked parcel Yes
51 Bring Tracked parcel No
52 Box It Parcel Locker Yes
53 Box It Parcel Shop Yes
54 Hermes Germany Parcel Shop Yes
55 Swiss Post Swiss Post Yes
56 DHL/USPS USPS Ground Service Yes
57 DHL/USPS USPS Priority Yes
58 BoxBerry Parcel Shop Yes
59 InPost UK InPost 24/7 Locker Returns Yes
60 Estafeta estafeta test Yes
61 Bring Bring UK Yes
62 Direct Link Malta Post Untracked Return No
64 CanPar Canpar Home Collection Yes
66 Parcel Point ParcelPoint Home Collection Yes
67 Parcel Point ParcelPoint Drop Off Yes
68 Aramex Australia Post Tracked Returns Yes
69 Collect+ CollectPlus Yes
71 Hermes Europe Mondial Relay Yes
72 Schenker Sweden Schenker Sweden Yes
73 GLS Denmark GLS Denmark Yes
74 Posti UB Posti UB Yes
75 ACP USPS Lite Yes
76 Hermes Europe Hermes Europe test carrier Yes
77 Mondial Mondial Relay Yes
Please note, that a carrier service availability is determined by a geographical coverage and your account settings.