API documentation API console

API navigation

General information Describes entry point, request method and allowed formats
Authorization API Authorization guide. How to use and acquire API credentials
Create order Register your order information
Get order Get your registered order information
Delete order Delete your registered order information
Search orders Search for your registered orders using various filters
Create return Register a return and acquire a shipping label
Search returns Search for your registered returns using various filters
Get return Get a complete information about your registered return, including shipping label
Get returned items Get a information about returned items using various filters
Request for prices Request for prices
Get first mile delivery prices Get a list of available couriers, services and prices by address.
Get Tracking Get all tracking events by providing a tracking number
Get Tracking events by date range Get all tracking events which occurred between a given date range
Check Availability Simple method for checking that API service available now
Get Tracking status codes description Description of digital tracking statuses
Code examples Code example in PHP

General information

Following API is designed to provide a complete set of tools to integrate with Intelligent Return
API entry point https://intelligentreturns.net/api
Request and response formats format depends on url path. Can be JSON or XML. JSON by default
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
Type Input data Output data

Authorization

Each API request requires login and api key keys sent via POST
Login is the same as admin panel login. API key can be generated on client's profile page

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>

Create order

Order info (* required)

Key Desc
order_reference * Order reference. Must be unique if "overwrite_data" flag set as FALSE.
order_date * mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
currency_code * Currency code(3 letters) ISO_4217
overwrite_data 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 Code that will allow a customer to return an item after return policy has been expired
phone Phone
email Email
export_date Unix timestamp of export date. Default value, will be applied to all items, if not specified in corresponding item field
export_awb Export air waybill. Default value, will be applied to all items, if not specified in corresponding item field
export_carrier_name Exporter company. Default value, will be applied to all items, if not specified in corresponding item field

Address info

Key Desc
contact_name Customer full name (Person)
company_name Company name
country Country code (ISO 3166-1 alpha-2)
state State
zip Zip/Post code
city City
addr1 Address line 1
addr2 Address line 2
addr3 Address line 3
neighborhood Neighborhood. Available only for Mexico

Item info (* required)

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
weight_uom K / L (1 letter)
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
export_date Unix timestamp of export date
export_awb Export air waybill
export_carrier_name Exporter company

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",
        "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_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"
            }
        ]
    }
}

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>
    <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>
    <export_awb>444444US</export_awb>
    <export_carrier_name>USPS</export_carrier_name>
    <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>
</order>

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>

Get order

Order info

Key Value
type Can be 'id' or 'reference'
val 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>

Data found:

If order was found, you will receive data in success field of JSON or XML format (depends on what format you've been 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"
            },
            {
                "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"
            }
        ]
    }
}

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</citygt;
    <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>
    </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>
    </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>

Delete order

You can delete order by internal id or reference
URL:
https://intelligentreturns.net/api/orders/delete
Key Value
type Can be 'id' or 'reference'
val 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>

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>

Search orders

URL:
https://intelligentreturns.net/api/orders/search
Filter data:
Key Value
date_from Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
date_to Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
quick_search Keywords divided by space. Each new keyword will narrow search results

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

JSON

URL:
https://intelligentreturns.net/api/orders/search/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",
        "quick_search":"GB"
    }
}

XML

URL:
https://intelligentreturns.net/api/orders/search/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>
    <quick_search>GB</quick_search>
</filter>

JSON response example:

{"success":{"id":["21","25","58","57","59","42","41","39","38","37"]}}

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <id>2901</id>
    <id>2902</id>
    <id>2903</id>
    <id>2904</id>
    <id>2906</id>
</success>

Nothing found:

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

Create return

Information of return (* required)

Key Desc
order_reference * order reference
date_added 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 * Carrier
The list of available carriers:
  • ACP
  • AnPost
  • ASM
  • boxit
  • Business Reply
  • canada_post
  • Correos
  • CTT
  • DHL
  • Direct Link
  • Hermes
  • hermes_germany
  • Kiala
  • MyPack
  • nzpost
  • Royal Mail
  • Royale
  • Self Post
  • swiss_post
service Shipping service type. Required for following carriers:
  • 'ACP' possible values:
    • 'Ground'
    • 'Priority'
  • 'ASM' possible values:
    • 'home_collection'
  • 'Hermes' possible values:
    • 'home_collection'
    • 'drop_off'
label_format 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 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 Currency code(3 letters) ISO_4217
phone Phone
email Email
display_id An additional information, which will be displayed on the shipping label (if it is possible). Max length 32 characters
external_id Alphanumeric value. Must be unique for each return. This field can be used in /returns/get/ method
add_items_data_to_order 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 Unix timestamp of export date. Default value, will be applied to all items, if not specified in corresponding item field
export_awb Export air waybill. Default value, will be applied to all items, if not specified in corresponding item field
export_carrier_name Exporter company. Default value, will be applied to all items, if not specified in corresponding item field
verification_entity TRUE is verification is needed, FALSE otherwise.
dangerous_goods Possible values: Yes/No. Default value, will be applied to all items, if not specified in corresponding item field
final_disposition Can be 'return' or 'destroy'. Default value, will be applied to all items, if not specified in corresponding item field

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.
Not required for following countries:
  • GB
  • UK
  • IL
  • DE
  • FR
  • NL
  • IE
  • SE
  • IT
  • DK
  • AT
  • LU
  • CZ
zip * Zip/Post code
Not required for following countries:
  • HK
  • IE
  • IL
city * City
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_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 (Not Required)

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
weight_uom K / L (1 letter)
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
export_date Unix timestamp of 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_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 TRUE is verification is needed, FALSE otherwise.
final_disposition 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>
    <name>John Doe</name>
    <phone>+010557779</phone>
    <email>doe@gmail.com</email>
    <addr1>City Hall</addr1>
    <addr2>24 Eagle Street, Room 102</addr2>
    <addr3></addr3>
    <city>Albany</city>
    <zip>12207</zip>
    <state>NY</state>
    <country>US</country>
    <display_id>123123123</display_id>
    <final_dest_id>Default</final_dest_id>
    <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>
    <final_dest_city>Telford</final_dest_city>
    <final_dest_zip>TF3 3BJ</final_dest_zip>
    <final_dest_state>West Midlands</final_dest_state>
    <final_dest_country>UK</final_dest_country>
    <carrier>acp</carrier>
    <service>ground</service>
    <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>

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>

Search returns

URL:
https://intelligentreturns.net/api/returns/search
Filter data:
Key Value
tracking Tracking code
date_from Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
date_to Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
quick_search Keywords divided by space. Each new keyword will narrow search results
order_reference Order reference

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

JSON

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

XML

URL:
https://intelligentreturns.net/api/returns/search/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>
    <tracking></tracking>
    <date_from>10/15/2015</date_from>
    <date_to>12/01/2015</date_to>
</filter>

JSON response example:

{"success":{"id":["2901","2902","2903","2904","2906"]}}

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <id>2901</id>
    <id>2902</id>
    <id>2903</id>
    <id>2904</id>
    <id>2906</id>
</success>

Nothing found:

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

Get return

Return info

Key Value
id
    Can be one of the following:
  • id
  • order_reference
  • external_id
You can get return information by internal id, external id or reference

You can provide a return 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>

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 TRUE is verification is needed, FALSE otherwise.

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
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_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
weight_uom K / L (1 letter)
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
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_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_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 TRUE is verification is needed, FALSE otherwise.
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>111495</id>
    <order_reference>12312355</order_reference>
    <date_added>1465397894</date_added>
    <name>John Doe</name>
    <zip>12207</zip>
    <email>doe@gmail.com</email>
    <addr1>City Hall</addr1>
    <addr2>24 Eagle Street, Room 102</addr2>
    <addr3></addr3>
    <city>Albany</city>
    <state>NY</state>
    <country>US</country>
    <phone>+010557779</phone>
    <tracking>9202490112676104136413</tracking>
    <tracking_last_update>1465397894</tracking_last_update>
    <current_tracking_status>10</current_tracking_status>
    <final_dest_id>Default</final_dest_id>
    <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>
    <final_dest_city>Telford</final_dest_city>
    <final_dest_zip>TF3 3BJ</final_dest_zip>
    <final_dest_state>West Midlands</final_dest_state>
    <final_dest_country>UK</final_dest_country>
    <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>
        <reason>
            <action>Exchange</action>
            <reason>Too small</reason>
            <wish></wish>
            <additional>
                <title>New size</title>
                <value>L</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>

Returned items

Filter data

Key Value
order_reference Order reference
date_from Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
date_to Allowed date formats: mm/dd/yyyy, yyyy/mm/dd, Unix timestamp
quick_search Keywords divided by space. Each new keyword will narrow search results
status 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
  • 21 - Additional Items
  • 900 - Processed on hub
current_tracking_status Digital code of current tracking status.
carrier Carrier. The list of available couriers:
  • 'ACP'
  • 'AnPost'
  • 'Business Reply'
  • 'Correos'
  • 'DHL'
  • 'Direct Link'
  • 'Kiala'
  • 'MyPack'
country Customer's country code (ISO 3166-1 alpha-2)
id_last 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>
</order>

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>111495</id>
        <order_reference>12312355</order_reference>
        <date_added>1465397894</date_added>
        <name>John Doe</name>
        <zip>12207</zip>
        <email>doe@gmail.com</email>
        <addr1>City Hall</addr1>
        <addr2>24 Eagle Street, Room 102</addr2>
        <addr3></addr3>
        <city>Albany</city>
        <state>NY</state>
        <country>US</country>
        <phone>+010557779</phone>
        <tracking>9202490112676104136413</tracking>
        <tracking_last_update>1465397894</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>ACP</carrier>
    </return>
    <return>
        <id>111494</id>
        <order_reference>12312355</order_reference>
        <date_added>1465397745</date_added>
        <name>John Doe</name>
        <zip>12207</zip>
        <email>doe@gmail.com</email>
        <addr1>City Hall</addr1>
        <addr2>24 Eagle Street, Room 102</addr2>
        <addr3></addr3>
        <city>Albany</city>
        <state>NY</state>
        <country>US</country>
        <phone>+010557779</phone>
        <tracking>9202490112676104136369</tracking>
        <tracking_last_update>1465397745</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 &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>ACP</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>

Request for prices

Information of return (* required)

Key Desc
order_reference * order reference
date_added 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 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 Currency code(3 letters) ISO_4217
phone Phone
email Email
display_id An additional information, which will be displayed on the shipping label (if it is possible). Max length 32 characters
external_id Alphanumeric value. Must be unique for each return. This field can be used in /returns/get/ method
add_items_data_to_order 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 Unix timestamp of export date. Default value, will be applied to all items, if not specified in corresponding item field
export_awb Export air waybill. Default value, will be applied to all items, if not specified in corresponding item field
export_carrier_name Exporter company. Default value, will be applied to all items, if not specified in corresponding item field
verification_entity TRUE is verification is needed, FALSE otherwise.
dangerous_goods Possible values: Yes/No. Default value, will be applied to all items, if not specified in corresponding item field
final_disposition Can be 'return' or 'destroy'. Default value, will be applied to all items, if not specified in corresponding item field

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
Not required for following countries:
  • GB
  • UK
  • IL
  • DE
  • FR
  • NL
  • IE
  • SE
  • IT
  • DK
  • AT
  • LU
  • CZ
zip * Zip/Post code
Not required for following countries:
  • HK
  • IE
  • IL
city * City
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_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
weight_uom K / L (1 letter)
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
export_date Unix timestamp of 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_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 TRUE is verification is needed, FALSE otherwise.
final_disposition Can be 'return' or 'destroy'.

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>
    <name>John Doe</name>
    <phone>+010557779</phone>
    <email>doe@gmail.com</email>
    <addr1>City Hall</addr1>
    <addr2>24 Eagle Street, Room 102</addr2>
    <addr3></addr3>
    <city>Albany</city>
    <zip>12207</zip>
    <state>NY</state>
    <country>US</country>
    <final_dest_id>Default</final_dest_id>
    <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>
    <final_dest_city>Telford</final_dest_city>
    <final_dest_zip>TF3 3BJ</final_dest_zip>
    <final_dest_state>West Midlands</final_dest_state>
    <final_dest_country>UK</final_dest_country>
    <currency_code>USD</currency_code>
    <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>

Successful request for prices:

{
    "success": {
        "result": [
            {
                "carrier": "ACP",
                "service": "ground",
                "first_mile_price": "17.95 USD",
                "parcel_processing_price": "2 USD",
                "final_mile_price": "5 USD",
                "customs_price": "1 USD",
                "government_duty_price": "2 USD"
            },
            {
                "carrier": "ACP",
                "service": "priority",
                "first_mile_price": "21.95 USD",
                "parcel_processing_price": "2 USD",
                "final_mile_price": "5 USD",
                "customs_price": "1 USD",
                "government_duty_price": "2 USD"
            }
        ]
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<success>
    <result>
        <carrier>ACP</carrier>
        <service>ground</service>
        <first_mile_price>17.95 USD</first_mile_price>
        <parcel_processing_price>2 USD</parcel_processing_price>
        <final_mile_price>5 USD</final_mile_price>
        <customs_price>1 USD</customs_price>
        <government_duty_price>2 USD</government_duty_price>
    </result>
    <result>
        <carrier>ACP</carrier>
        <service>priority</service>
        <first_mile_price>21.95 USD</first_mile_price>
        <parcel_processing_price>2 USD</parcel_processing_price>
        <final_mile_price>5 USD</final_mile_price>
        <customs_price>1 USD</customs_price>
        <government_duty_price>2 USD</government_duty_price>
    </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>

Get first mile delivery prices

URL:
https://intelligentreturns.net/api/returns/prices
Return data:
Key Value
country * Country code (ISO 3166-1 alpha-2)
zip (Preferred) Zip/Post code
state (Preferred) Customer's state
city (Preferred) City
addr1 (Preferred) Address line 1
addr2 Address line 2
addr3 Address line 3

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

JSON

URL:
https://intelligentreturns.net/api/returns/prices/json
POST:
Key Value
login your login
api_key your API key
request JSON example
Always apply urlencode to json data!
{
    "return":
    {
        "country": "GB",
        "zip":"SW1A 0AA",
        "state":"",
        "city":"London",
        "addr1":"address line",
        "addr2":"",
        "addr3":""
    }
}

XML

URL:
https://intelligentreturns.net/api/returns/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>
    <country>GB</country>
    <zip>SW1A 0AA</zip>
    <state></state>
    <city>London</city>
    <addr1>address line</addr1>
    <addr2></addr2>
    <addr3></addr3>
</return>

JSON response example:

{
    "success": {
        "price" : [
            {
                "currency": "GBP",
                "price": "2.50",
                "carrier": "Hermes",
                "service": "drop_off"
            },
            {
                "currency": "GBP",
                "price": "3.95",
                "carrier": "Hermes",
                "service": "home_collection"
            }
        ]
    }
}

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <price>
        <currency>GBP</currency>
        <price>2.50</price>
        <carrier>Hermes</carrier>
        <service>drop_off</service>
    </price>
    <price>
        <currency>GBP</currency>
        <price>3.95</price>
        <carrier>Hermes</carrier>
        <service>home_collection</service>
    </price>
</success>

Nothing found:

{"error":{"code":"country_empty","message":["Country is required."]}}
<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>country_empty</code>
    <message>Country is required.</message>
</error>

Tracking get

URL:
https://intelligentreturns.net/api/tracking/get
Filter data:
Key Value
tracking 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": "1234567"
    }
}

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>1234567</code>
</tracking>

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

Location

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

JSON response example:

{
    "success": {
        "track": [
            {
                "dt": "1471346494",
                "status": "10",
                "location": {
                    "country": "GB",
                    "state": "Shropshire",
                    "city": "Telford"
                }
            },
            {
                "dt": "1472028798",
                "status": "40",
                "location": {
                    "country": "GB",
                    "state": "West Midlands",
                    "city": "Telford"
                }
            },
            {
                "dt": "1473365973",
                "status": "45",
                "location": {
                    "country": "GB",
                    "state": "West Midlands",
                    "city": "Telford"
                }
            }
        ],
        "pallet_number": "00000000006"
    }
}

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
    <track>
        <dt>1471346494</dt>
        <status>10</status>
        <location>
            <country>GB</country>
            <state>Shropshire</state>
            <city>Telford</city>
        </location>
    </track>
    <track>
        <dt>1472028798</dt>
        <status>40</status>
        <location>
            <country>GB</country>
            <state>West Midlands</state>
            <city>Telford</city>
        </location>
    </track>
    <track>
        <dt>1473365973</dt>
        <status>45</status>
        <location>
            <country>GB</country>
            <state>West Midlands</state>
            <city>Telford</city>
        </location>
    </track>
    <pallet_number>00000000006</pallet_number>
</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>

Tracking events by date range

URL:
https://intelligentreturns.net/api/tracking/get_by_date_range
Filter data:
Key Value
date_from * mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp
date_to * mm/dd/yyyy hh:mm:ss, yyyy/mm/dd hh:mm:ss, Unix timestamp

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

JSON

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

XML

URL:
https://intelligentreturns.net/api/tracking/get_by_date_range/xml
POST:
Key Value
login your login
api_key your API key
request XML Example
Warning! Before send xml data:
  1. Convert xml special characters
  2. Apply urlencode to xml data
<filter>
    <date_from>2017/02/24 06:42:19</date_from>
    <date_to>2017/02/25 06:42:19</date_to>
</filter>
Please note, this method allows to get up to 20000 events. Make sure that a date range provided is not too wide.

Response fields. Tracking events grouped by tracking numbers.

Key Value
tracking_number Tracking number
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": {
         "512902295639": {
            "tracking_number": "512902295639",
            "events": [
               {
                  "status": "10",
                  "dt": "1475087846",
                  "location": {
                     "country": "SK",
                     "state": "Slovensko",
                     "city": "Bratislava"
                  }
               }
            ]
         },
         "00350559268102004358": {
            "tracking_number": "00350559268102004358",
            "events": [
               {
                  "status": "20",
                  "dt": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Uppsala"
                  }
               },
               {
                  "status": "30",
                  "dt": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Uppsala"
                  }
               }
            ]
         },
         "00350559268102018270": {
            "tracking_number": "00350559268102018270",
            "events": [
               {
                  "status": "30",
                  "dt": "1475087880",
                  "location": {
                     "country": "SE",
                     "state": "",
                     "city": "Landvetter"
                  }
               }
            ]
         }
      }
   }
}

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<success>
   <tracking_data>
      <tracking_number>512902295639</tracking_number>
      <events>
         <status>10</status>
         <dt>1475087846</dt>
         <location>
            <country>SK</country>
            <state>Slovensko</state>
            <city>Bratislava</city>
         </location>
      </events>
   </tracking_data>
   <tracking_data>
      <tracking_number>00350559268102004358</tracking_number>
      <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>
      <events>
         <status>30</status>
         <dt>1475087880</dt>
         <location>
            <country>SE</country>
            <state />
            <city>Landvetter</city>
         </location>
      </events>
   </tracking_data>
</success>

Nothing found:

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

Check Availability

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

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": "unavailable",
        "message":["Server is temporary unavailable."]
    }
}

XML UNAVAILABLE response example:

<?xml version="1.0" encoding="UTF-8"?>
<error>
    <code>
        unavailable
    </code>
    <message>
        Server is temporary unavailable.
    </message>
</error>

Tracking status list

Code Description
10 Return registered online
20 Received by the carrier
30 In transit to our local hub
40 Received at our local hub
45 Parcel has been added to pallet
90 Parcel has been extracted from pallet
50 In transit to the retailer
60 Delivered to the retailer
70 Parcel refunded by retailer
100 Parcel delayed
110 Parcel lost
200 Parcel under investigation
120 Collection attempt failed
A list of all possible tracking status codes.

Code Examples

"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 didn't create
    $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, сheck 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.');