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
79 DHL Service Point DHL Service Point
94 Doddle Doddle
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.
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.
virtual_tracking_status int Digital code of current virtual 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.
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
cancellation_time_expired Return cancellation period has been expired
can_not_cancel_return Can not cancel return

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
order_reference Order reference, 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",
      "order_reference": "Order Reference"
   }
}
        

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>
   <order_reference>Order Reference</order_reference>
</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
request_wrong Request field is wrong.
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)
page int Page number. "1" by default.
count_per_page int Count of events on one response. By default 20000. Maximum value is 20000.

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": "2018/05/20 08:30:35",
        "date_to": "2018/05/21 08:30:35"
    }
}

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>2018/05/20 08:30:35</date_from>
    <date_to>2018/05/21 08:30:35</date_to>
</filter>

Output data


Please note that the tracking events count is limited by count_per_page for each request. Maximum value of count_per_page is 20000. In case total events count exceeds 20000, you can iterate through result pages using the field "page" which begins from 1. Please also note that the "total_events_count" represents total tracking events count, not tracking numbers.

Response fields.

Key Value
tracking_data Tracking data
total_events_count Number of the total tracking events found
current_page Number of the current page
total_pages_count Number of total pages
count_per_page Count of events on one response.

Tracking data. 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
order_reference Order reference, 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": "",
            "order_reference": "Order Reference",
            "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": "",
            "order_reference": "Order Reference",
            "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": "",
            "order_reference": "Order Reference",
            "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": "",
            "order_reference": "Order Reference",
            "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": "",
            "order_reference": "Order Reference",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087940",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Stockholm"
                  }
               },
               {
                  "status": "30",
                  "dt": "1475087940",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Stockholm"
                  }
               }
            ]
         }
      ],
      "total_events_count": 7,
      "current_page": 1,
      "total_pages_count": 1,
      "count_per_page": 20000
   }
}
        

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 />
      <order_reference>Order Reference</order_reference>
      <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 />
      <order_reference>Order Reference</order_reference>
      <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 />
      <order_reference>Order Reference</order_reference>
      <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 />
      <order_reference>Order Reference</order_reference>
      <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 />
      <order_reference>Order Reference</order_reference>
      <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>
   <total_events_count>7</total_events_count>
   <current_page>1</current_page>
   <total_pages_count>1</total_pages_count>
   <count_per_page>20000</count_per_page>
</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
request_wrong 'Filter' field is missing
page_wrong Page must be positive int.
count_per_page_wrong Count per page must be positive int.
count_per_page_max Maximum value of count per page is 20000.
empty No tracking events was found
date_filter_is_missing Date range is incorrect. See detailed description in error message

Input data


URL:
https://intelligentreturns.net/api/tracking/get_by_date_added_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)
page int Page number. "1" by default.
count_per_page int Count of events on one response. By default 20000. Maximum value is 20000.

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

JSON

URL:
https://intelligentreturns.net/api/tracking/get_by_date_added_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": "2018/05/20 08:30:35",
        "date_to": "2018/05/21 08:30:35"
    }
}

XML

URL:
https://intelligentreturns.net/api/tracking/get_by_date_added_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>2018/05/20 08:30:35</date_from>
    <date_to>2018/05/21 08:30:35</date_to>
</filter>

Output data


Please note that the tracking events count is limited by count_per_page for each request. Maximum value of count_per_page is 20000. In case total events count exceeds 20000, you can iterate through result pages using the field "page" which begins from 1. Please also note that the "total_events_count" represents total tracking events count, not tracking numbers.

Response fields.

Key Value
tracking_data Tracking data
total_events_count Number of the total tracking events found
current_page Number of the current page
total_pages_count Number of total pages
count_per_page Count of events on one response.

Tracking data. 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
order_reference Order reference, which can be populated using Create return method
events Tracking events. Contains: status, dt, date_added, location

Events

Key Value
status Digital code of current tracking status.
dt Date when tracking event was occurred in unix timestamp format.
date_added Date when tracking event was added to system 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": "",
            "order_reference": "Order Reference",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087880",
                  "date_added": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Uppsala"
                  }
               },
               {
                  "status": "30",
                  "dt": "1475087880",
                  "date_added": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Uppsala"
                  }
               }
            ]
         },
         {
            "tracking_number": "00350559268102018270",
            "pallet_number": "",
            "source_country": "SE",
            "carrier_name": "MyPack",
            "service_id": "40",
            "external_id": "",
            "order_reference": "Order Reference",
            "events": [
               {
                  "status": "30",
                  "dt": "1475087880",
                  "date_added": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Landvetter"
                  }
               }
            ]
         },
         {
            "tracking_number": "00350559268102009469",
            "pallet_number": "",
            "source_country": "SE",
            "carrier_name": "MyPack",
            "service_id": "40",
            "external_id": "",
            "order_reference": "Order Reference",
            "events": [
               {
                  "status": "30",
                  "dt": "1475087940",
                  "date_added": "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": "",
            "order_reference": "Order Reference",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087940",
                  "date_added": "1475087940",
                  "location": {
                     "country": "RO",
                     "state": "",
                     "city": ""
                  }
               }
            ]
         },
         {
            "tracking_number": "00350559268102026343",
            "pallet_number": "",
            "source_country": "SE",
            "carrier_name": "MyPack",
            "service_id": "40",
            "external_id": "",
            "order_reference": "Order Reference",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087940",
                  "date_added": "1475087940",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Stockholm"
                  }
               },
               {
                  "status": "30",
                  "dt": "1475087940",
                  "date_added": "1475087940",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Stockholm"
                  }
               }
            ]
         }
      ],
      "total_events_count": 7,
      "current_page": 1,
      "total_pages_count": 1,
      "count_per_page": 20000
   }
}
        

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 />
      <order_reference>Order Reference</order_reference>
      <events>
         <status>20</status>
         <dt>1475087880</dt>
         <date_added>1475087880</date_added>
         <location>
            <country>SE</country>
            <state />
            <city>Uppsala</city>
         </location>
      </events>
      <events>
         <status>30</status>
         <dt>1475087880</dt>
         <date_added>1475087880</date_added>
         <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 />
      <order_reference>Order Reference</order_reference>
      <events>
         <status>30</status>
         <dt>1475087880</dt>
         <date_added>1475087880</date_added>
         <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 />
      <order_reference>Order Reference</order_reference>
      <events>
         <status>30</status>
         <dt>1475087940</dt>
         <date_added>1475087940</date_added>
         <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 />
      <order_reference>Order Reference</order_reference>
      <events>
         <status>20</status>
         <dt>1475087940</dt>
         <date_added>1475087940</date_added>
         <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 />
      <order_reference>Order Reference</order_reference>
      <events>
         <status>20</status>
         <dt>1475087940</dt>
         <date_added>1475087940</date_added>
         <location>
            <country>SE</country>
            <state />
            <city>Stockholm</city>
         </location>
      </events>
      <events>
         <status>30</status>
         <dt>1475087940</dt>
         <date_added>1475087940</date_added>
         <location>
            <country>SE</country>
            <state />
            <city>Stockholm</city>
         </location>
      </events>
   </tracking_data>
   <total_events_count>7</total_events_count>
   <current_page>1</current_page>
   <total_pages_count>1</total_pages_count>
   <count_per_page>20000</count_per_page>
</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
request_wrong 'Filter' field is missing
page_wrong Page must be positive int.
count_per_page_wrong Count per page must be positive int.
count_per_page_max Maximum value of count per page is 20000.
empty No tracking events was found
date_filter_is_missing Date range is incorrect. See detailed description in error message

Input data


Request data (* required)

Key Type Value
tracking_status * object Tracking status request object

tracking_status

tracking * string(255) Tracking number.
date * string | int Date when tracking event was occurred (mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp)
status * int Digital code of current tracking status.
Allowed statuses:
Status code Status description
70 Parcel refunded by retailer
date_added string | int Date when tracking event was added (mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp)
description string Status description
carrier_status string(255) Carrier status code
location object Location

Location

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

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

JSON

URL:
https://intelligentreturns.net/api/tracking/add_status/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "tracking_status":
    {
        "tracking": "540324195682",
        "date": 1475087880,
        "status": 30,
        "description": "Test description",
        "carrier_status": "123ABC",
        "location":
        {
            "country": "GB",
            "state": "Greater London",
            "city": "London"
        }
    }
}

XML

URL:
https://intelligentreturns.net/api/tracking/add_status/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_status>
    <tracking>540324195682</tracking>
    <date>1475087880</date>
    <status>30</status>
    <description>Test description</description>
    <carrier_status>123ABC</carrier_status>
    <location>
        <country>GB</country>
        <state>Greater London</state>
        <city>London</city>
    </location>
</tracking_status>

Output data


Return update successfully:

{
    "success":
    {
        "code": "success",
        "message": [
            "Return 540324195682 update successfully"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<success>
    <code>success</code>
    <message>Return 540324195682 update successfully</message>
</success>

Incorrect return data:

{
    "error": {
        "code": "status_incorrect",
        "message": [
            "Status incorrect"
        ]
    }
}
        
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>status_incorrect</code>
    <message>Status incorrect</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
request_wrong 'tracking_status' field is missing
tracking_required tracking field is required
date_required date field is required
status_required status field is required
incorrect_date Incorrect date
incorrect_date_added Incorrect date_added
incorrect_status Incorrect tracking status
status_not_allowed Tracking status not allowed for add
return_not_found Return not found
status_already_present Return has current/later status already
has_later_date Return has a later date

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

Tracking status codes.


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
110 Parcel lost
310 Canceled

Virtual tracking status codes.


Code Description
70 Parcel refunded by retailer
100 Parcel delayed
120 Collection attempt failed
200 Parcel under investigation
201 Awaiting customs clearance
202 Customs clearance completed
300 Cancel requested

"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 Ground Return Service Yes
2 ACP Priority Mail Return Service Yes
3 Canada Post Canada Post Tracked 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 Return 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 Ground Return Service Yes
57 DHL/USPS Priority Mail Return Service 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 Yes
74 Posti UB Posti Tracked Parcel Yes
75 ACP First Class Package Return Service Yes
76 Hermes Europe Hermes Europe test carrier Yes
77 Mondial Mondial France Yes
78 UPS UPS Access Point Yes
79 DHL Service Point DHL Service Point Yes
81 Mondial Mondial Belgium Yes
82 Mondial Mondial Spain Yes
83 Malta Post Malta Post Tracked Return Yes
85 UPS UPS Access Point NL Yes
86 Omniva Omniva Parcel Locker Yes
87 Collissimo Colissimo Tracked Return Yes
88 Collissimo Colissimo Letter Box Collection Yes
89 To You ToYou Yes
90 DHL BPost Tracked Return Yes
91 UPS UPS Access Point US Yes
94 Doddle Doddle Yes
96 Direct Link Merchanise Mail (Norway) No
97 UPS UPS Access Point Yes
98 Pakpobox Alfred Parcel Locker Yes
99 UPS UPS Italy Yes
100 UPS UPS Austria Yes
101 UPS UPS Netherlands Yes
102 UPS UPS Poland Yes
103 UPS UPS Germany Yes
104 UPS UPS France Yes
105 SDA Express SDA Express Yes
106 DHL Retoure DHL Retoure Yes
107 SF Express SF Express Yes
109 DPD DPD Yes
Please note, that a carrier service availability is determined by a geographical coverage and your account settings.