You're currenty viewing the API documentation for Returnless V1. In case the URL of your account starts with panel.returnless.com, you're using Returnless V2. Click here to view documentation for V2.
Back to Returnless.com

Introduction

Welcome to the Returnless Developer API documentation. You can use our API in case you want to develop your own custom integration with our platform. We also provide pre-build integrations in case you're using any of our supported platforms. Please have a look at our Integrations page for the available integrations.

Basics

HTTPS and JSON Only

The Returnless API is only accessible through HTTPS and requests and responses are always JSON formatted.

Rate limiting

There is a rate limit per user per IP address. If you get rate limited, we return an empty response with HTTP status code 429.

Authentication

Generate API credentials

Login to your return portal and navigate to the API keys section. There you can generate a new API user and API password.

Add the API credentials to your request

Use Basic Auth to set the API user and API password and connect with the API.

Changelog

23 January 2023

Added a width, length and height to the Order Info response.

2 November 2022

Introducing a new "Shipments" endpoint 📦.

1 November 2022

Added "return_notes" to the Requests endpoint.
Added "return_notes" to the Returns endpoint.

13 Oktober 2022

Added "files" to the Returns endpoint.

9 September 2022

Added "return_questions" to the Returns webhook.

8 September 2022

Added "shipping_label_link" to the Returns webhook.

1 September 2022

Added "shipping_label_link" to the Returns endpoint.

15 July 2022

Added "return_questions" to the Returns endpoint.

12 July 2022

Added option to PUT Requests endpoint: Toggle free_shipping 0 or 1 to decide if a request can be returned for free or not.

4 May 2022

Added new feature "force_address" to the Get Order Info endpoint.

3 May 2022

Added "return_type" parameter to the Returns endpoint.

13 April 2022

Added a "sort_order" parameter to the Requests and Returns endpoint to sort by oldest or newest items. Happy sorting! 🔝

7 April 2022

Added an "updated_after" filter to the Requests endpoint.

5 April 2022

Added the "shipping_description" to the Returns response.

23 February 2022

Added an "updated_after" filter to the Returns endpoint.

4 October 2021

Added a per_page parameter to the Requests and Returns endpoint.

26 Augustus 2021

Added a filter possibility to the Requests endpoint.

17 Augustus 2021

Added a filter possibility to the Returns endpoint.

1 Augustus 2021

Added the new Requests endpoint to get and update return requests.

30 March 2021

Added the new Returns endpoint to get and update returns.

16 February 2021

We've added a Phone field in the customer container. When you provide us with a Phone number of your customer, we will add it to a Gate-Keeper request. Also the phone number is used when creating a Budbee shipment as they require it for sending notifications for the pick-up.

28 December 2020

We've added a Country field in the billing_address container. When you provide us with a Country code in the response, we will prefill it for your customer.

11 December 2020

Added parameter descriptions for Order Info API.

17 November 2020

Initial release of our API 🎉

Order Info API

The Order Info API is used to send us all relevant data about an order when a customer clicks the "Find Order" button in the return form. See a live example of the return form here:

https://www.returnform.com/shirtstore?orderid=ORD000212&email=klant.peter@gmail.com

Authentication

You can generate an API key in your portal. Go to Return Forms and find your API-key in the Webshop Integration tab:

  • API Key: Your API key. If you're unable to generate a new API-key, please contact us.
  • Platform URL: Enter the URL where we should lookup the order, with a leading slash (e.g. "https://www.yourdomain.com/api/v1/orders/").

Note

When we request the order information and the authentication is successful, you can safely output the order details. Based on the order information we will validate if the customer email corresponds with the order email. Order details will only be shown to the customer once this validation has succeeded on our side.

When a customer enters their Order ID and email address in the return form, we will make a GET request to your website using the URL entered in the Platform URL configuration:

https://www.yourdomain.com/api/v1/orders/ORD000123

To validate that it is us making the request to your server, we will add a returnless-signature in the header of the request:


returnless-signature: 4c7feb66d66873ec79c81cd8beb811f34e4ee37d9d24a407712b58049b08da9f

The signature is a HMAC-SHA256 encrypted hash of the Order ID, using your API key as the secret key. To authenticate, create your own encrypted hash of the Order ID using your API key as the secret key. If your signature is the same as the returnless-signature, you're good to go :)

PHP Example

Here is an example in PHP:

Expected response

If authentication is successful, you can output the order information as a JSON response. Please add the content-type to the header:


Content-Type: application/json; charset=utf-8

Required parameters:

Name Type Description
id string The Order ID known by your customer.
order_id string Your internal Order reference.
create_at date The date the order was created.
email email The email address that was used for the order.
order_products.product_id string The internal ID of the product.
order_products.quantity integer The quantity of the product that was ordered.
order_products.title_name string The name of the parent product.
order_products.price_inc_tax decimal The price including tax of the product.

Additional parameters:

Name Type Description
force_address json Use the force_address parameter to overrule your default return address. This can be useful in case you want to return a product to an alternative warehouse. Some remarkts:
  • Please note that since we do not offer different return addresses within one return, all return items will be sent to this address when the item with the force_address parameter is selected to be returned.
  • You can only use the same country as your primary return address.
  • In case you send us multiple force_address parameters we will use the last one. 
    {
    "return_code": 200,
    "return_message": "Success!",
    "result": {
        "id": "ORD000123",
        "order_id": "124006",
        "create_at": {
            "value": "2020-09-05 10:46:27"
        },
        "payment_method": {
            "name": "iDeal"
        },
        "customer": {
            "id": "58179",
            "email": "pieter@returnless.com",
            "phone": "+31612341234"
        },
        "billing_address": {
            "first_name": "Pieter",
            "last_name": "Post",
            "postcode": "5611NV",
            "country": {
                "code2": "NL"
                },
            "city": "Eindhoven",
            "address1": "PCzn Hooftlaan",
            "address2": "14",
            "addition": ""
        },
        "order_products": [
            {
                "product_id": "1007",
                "quantity": "1.0000",
                "order_product_id": "153397",
                "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                "title_name": "Samsonite S'Cure Spinner 55",
                "model": "trvl-01598592",
                "article_code": "495398926",
                "price": "144.6300",
                "price_inc_tax": "175.0000",
                "discount_amount": "26.0000",
                "total_price": "149.8000",
                "cost": "87.50",
                "weight": "2.9000",
                "length": "50",
                "width": "40",
                "height": "30",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                "categories_ids": [
                    "520",
                    "157"
                    ],
                "u_brand": "Samsonite",
                "u_upc": "890128492109899"
            },
            {
                "product_id": "1008",
                "quantity": "2.0000",
                "order_product_id": "153398",
                "name": "Eastpak x Havaianas Padded Pak'R Rugzak havaianas green",
                "title_name": "Eastpak x Havaianas Padded Pak'R Rugzak",
                "model": "trvl-1059819",
                "article_code": "EK000620C411001",
                "price": "45.4500",
                "price_inc_tax": "55.0000",
                "discount_amount": "20.1000",
                "total_price": "69.8000",
                "cost": "21.90",
                "weight": "1.5000",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/362798/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/eastpak-x-havaianas-padded-pakr-rugzak-havaianas-green.html",
                "categories_ids": [
                    "520",
                    "157"
                    ],
                "u_brand": "Eastpack",
                "u_upc": "5400879259557",
                "force_address": {
                  "name": "My secondary warehouse",
                  "address": "Singel",
                  "house_number": "1",
                  "postal_code": "1234 AB",
                  "city": "Amsterdam",
                  "country": "NL"
                }
            }
        ]
    }
}

Requests endpoint

Basics

Use this endpoint to get or update return requests in Returnless.

Request statuses

Here is a description of all statuses that we use for requests:

Status Description
concept Request has been created by the webshop but has not yet been sent to the customer.
open Request has been created by the customer and is awaiting review.
expired The expiration time has passed. Customer can not create a return.
on_hold Webshop has set the status On Hold. Customer can not create a return.
cancelled Request has been cancelled.
approved Request has been approved by the webshop. The customer can create a return.
approved_without_shipment Request has been approved by the webshop. The customer does not have to return the order.
rejected Request has been rejected by the webshop. Customer can not create a return.
customer_viewed Request has been approved by the webshop and seen by the customer. However no return label has been created yet.
label_created Request has been approved by the webshop and a return label has been created by the customer.

Get all requests

GET 
https://api.returnless.com/requests

Parameters

Parameter Description Example
per_page Set the amount of items that you want to show per page in your response. Choose a range between 1-200. 150
sort_order Use 'desc' to show newest items first (default) or use 'asc' to show oldest items first. asc

Filters

Attribute Description Example
reference The Order number known by your customer. ORD00012
order_id Your internal Order reference. 194019
created_after Get all requests created after a specific date. 2021-02-15 00:00:00
emailaddress The customer email address that was used for the order.
status Get all requests with a specific status. received
updated_after Get all requests with a status changed after a certain DateTime. 2022-02-01+00:00:00

Example with filter

https://api.returnless.com/requests?emailaddresss=klant.peter@gmail.com&status=approved
RESPONSE 
HTTP/1.1 200 OK

[
    {
        "request_id": "948191",
        "request": "GK000102092019",
        "status": "processing",
        "reference": "ORD000123",
        "order_id": "124006",
        "order_date": "2021-01-10 10:46:27",
        "request_date": "2021-01-20 11:52:42",
        "form": "5919",
        "customer_id": "58179",
        "customer_email": "pieter@returnless.com",
        "billing_address": {
            "first_name": "Pieter",
            "last_name": "Post",
            "postcode": "5611NV",
            "country": "NL",
            "city": "Eindhoven",
            "address1": "PCzn Hooftlaan",
            "address2": "14",
            "addition": ""
        },
        "return_notes": [
                {
                    "message": "The status has been changed from Open to Approved",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:45"
                },
                {
                    "message": "I have contacted the customer and everything is fine.",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:59"
                }
        ],
        "returned_products": [
            {
                "return_item_id": "1458191",
                "product_id": "1007",
                "qty_ordered": "1.0000",
                "qty_returned": "1.0000",
                "qty_received": "0.0000",
                "order_product_id": "153397",
                "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                "title_name": "Samsonite S'Cure Spinner 55",
                "model": "trvl-01598592",
                "article_code": "495398926",
                "cost": "87.50",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                "u_brand": "Samsonite",
                "ean": "890128492109899",
                "reason_id": "2",
                "reason": "Size too small",
                "back_to_stock": "1",
                "remarks": ""
            }
        ]
    }
]

Get single request

GET 
https://api.returnless.com/requests/{request_id}
RESPONSE 
HTTP/1.1 200 OK

    {
        "request_id": "948191",
        "request": "GK000102092019",
        "status": "processing",
        "reference": "ORD000123",
        "order_id": "124006",
        "order_date": "2021-01-10 10:46:27",
        "request_date": "2021-01-20 11:52:42",
        "form": "5919",
        "customer_id": "58179",
        "customer_email": "pieter@returnless.com",
        "billing_address": {
            "first_name": "Pieter",
            "last_name": "Post",
            "postcode": "5611NV",
            "country": "NL",
            "city": "Eindhoven",
            "address1": "PCzn Hooftlaan",
            "address2": "14",
            "addition": ""
        },
        "return_notes": [
                {
                    "message": "The status has been changed from Open to Approved",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:45"
                },
                {
                    "message": "I have contacted the customer and everything is fine.",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:59"
                }
        ],
        "returned_products": [
            {
                "return_item_id": "1458191",
                "product_id": "1007",
                "qty_ordered": "1.0000",
                "qty_returned": "1.0000",
                "qty_received": "0.0000",
                "order_product_id": "153397",
                "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                "title_name": "Samsonite S'Cure Spinner 55",
                "model": "trvl-01598592",
                "article_code": "495398926",
                "cost": "87.50",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                "u_brand": "Samsonite",
                "ean": "890128492109899",
                "reason_id": "2",
                "reason": "Size too small",
                "back_to_stock": "1",
                "remarks": ""
            }
        ]
    }

Update request

Use the PUT parameter to update a request.

PUT 
https://api.returnless.com/requests/{request_id}?status=completed

Parameters

Parameter Description Example
status Change the status of a request You can use any of the supported request states. ?status=completed
free_shipping Set 1 to enable a free return shipment for this request. Set 0 to disable free shipment and let the customer pay for the return shipment. ?free_shipping=1
RESPONSE 
{
    "result": true,
    "message": "Request updated successfully!"
}

Returns endpoint

Basics

Use this endpoint to get or update returns in Returnless.

Return statuses

Here is a description of all statuses that we use for returns:

Status Description
processing Return has been created by customer.
received Return has been received by the webshop and has to be checked.
complete Return has been auto-approved without shipment by Return Rules.
checked Return has been approved by the webshop.
re-check Return has to be re-checked by the webshop.
completed Return has been refunded by the webshop.
declined Return has been refused by the webshop.
delivered Return has been received, approved, refunded and processed in accounting software.
exception Return has an exception.
exchanged Products have been exchanged for a new product.
pending_payment Return label is not created yet. Returnless is awaiting payment by customer.
closed Return label has been cancelled and the payment for the return label has been refunded by Returnless.

Get all returns

GET 
https://api.returnless.com/returns

Parameters

Parameter Description Example
per_page Set the amount of items that you want to show per page in your response. Choose a range between 1-200. 150
sort_order Use 'desc' to show newest items first (default) or use 'asc' to show oldest items first. asc

Filters

Attribute Description Example
reference The Order number known by your customer. ORD00012
order_id Your internal Order reference. 194019
created_after Get all returns created after a specific date. 2021-02-15 00:00:00
emailaddress The customer email address that was used for the order.
status Get all returns with a specific status. received
updated_after Get all returns with a status changed after a certain DateTime. 2022-02-01+00:00:00

Example with filter

https://api.returnless.com/returns?emailaddresss=klant.peter@gmail.com&status=approved
RESPONSE 
HTTP/1.1 200 OK

[
    {
        "return_id": "948191",
        "return": "RENL1641091121",
        "status": "processing",
        "return_type": "coupon",
        "reference": "ORD000123",
        "order_id": "124006",
        "order_date": "2021-01-10 10:46:27",
        "return_date": "2021-01-20 11:52:42",
        "updated_at": "2021-01-21 21:29:59",
        "form": "5919",
        "customer_id": "58179",
        "customer_email": "pieter@returnless.com",
        "request_id": "481049",
        "shipping_description": "PostNL inleveren bij pakketpunt",
        "tracking_number": "3STRVL58192041",
        "tracking_status_id": "1000",
        "tracking_status": "Ready to Send",
        "tracking_url": "https://jouw.postnl.nl/track-and-trace/3STRVL58192041-NL-5611NV",
        "shipping_label_link": "https://www.returnless.com/shippinglabel/index/?scid=3SRLSS001989339&hash=hsFMhN544bhKD57wk9QDJxjsUJ",
        "files": [
            "https://www.retourneren.nl/sales/download/downloadCustomOption/id/8304498/key/1f96k3FAZG9exk6"
        ],
        "return_questions": [
            {
                "option_id": "46363",
                "label": "Please describe the damage.",
                "value": "There is a stain on the t-shirt."
            }
        ],
        "billing_address": {
            "first_name": "Pieter",
            "last_name": "Post",
            "postcode": "5611NV",
            "country": "NL",
            "city": "Eindhoven",
            "address1": "PCzn Hooftlaan",
            "address2": "14",
            "addition": ""
        },
        "return_notes": [
                {
                    "message": "The status has been changed from Open to Approved",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:45"
                },
                {
                    "message": "I have contacted the customer and everything is fine.",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:59"
                }
        ],
        "returned_products": [
            {
                "return_item_id": "1458191",
                "product_id": "1007",
                "qty_ordered": "1.0000",
                "qty_returned": "1.0000",
                "qty_received": "0.0000",
                "order_product_id": "153397",
                "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                "title_name": "Samsonite S'Cure Spinner 55",
                "model": "trvl-01598592",
                "article_code": "495398926",
                "cost": "87.50",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                "u_brand": "Samsonite",
                "ean": "890128492109899",
                "reason_id": "2",
                "reason": "Size too small",
                "back_to_stock": "1",
                "remarks": ""
            }
        ]
    }
]

Get single return

GET 
https://api.returnless.com/returns/{return_id}
RESPONSE 
HTTP/1.1 200 OK

    {
        "return_id": "948191",
        "return": "RENL1641091121",
        "status": "processing",
        "reference": "ORD000123",
        "order_id": "124006",
        "order_date": "2021-01-10 10:46:27",
        "return_date": "2021-01-20 11:52:42",
        "updated_at": "2021-01-21 22:19:58",
        "form": "5919",
        "customer_id": "58179",
        "customer_email": "pieter@returnless.com",
        "request_id": "481049",
        "shipping_description": "PostNL inleveren bij pakketpunt",
        "tracking_number": "3STRVL58192041",
        "tracking_status_id": "1000",
        "tracking_status": "Ready to Send",
        "tracking_url": "https://jouw.postnl.nl/track-and-trace/3STRVL58192041-NL-5611NV",
        "shipping_label_link": "https://www.returnless.com/shippinglabel/index/?scid=3SRLSS001989339&hash=hsFMhN544bhKD57wk9QDJxjsUJ",
        "files": [
            "https://www.retourneren.nl/sales/download/downloadCustomOption/id/8304498/key/1f96k3FAZG9exk6"
        ],
        "return_questions": [
            {
                "option_id": "46363",
                "label": "Please describe the damage.",
                "value": "There is a stain on the t-shirt."
            }
        ],
        "billing_address": {
            "first_name": "Pieter",
            "last_name": "Post",
            "postcode": "5611NV",
            "country": "NL",
            "city": "Eindhoven",
            "address1": "PCzn Hooftlaan",
            "address2": "14",
            "addition": ""
        },
        "return_notes": [
                {
                    "message": "The status has been changed from Open to Approved",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:45"
                },
                {
                    "message": "I have contacted the customer and everything is fine.",
                    "name": "Returnless Support",
                    "quote_id": 408516,
                    "created_at": "2022-05-13 13:29:59"
                }
        ],
        "returned_products": [
            {
                "return_item_id": "1458191",
                "product_id": "1007",
                "qty_ordered": "1.0000",
                "qty_returned": "1.0000",
                "qty_received": "0.0000",
                "order_product_id": "153397",
                "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                "title_name": "Samsonite S'Cure Spinner 55",
                "model": "trvl-01598592",
                "article_code": "495398926",
                "cost": "87.50",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                "u_brand": "Samsonite",
                "ean": "890128492109899",
                "reason_id": "2",
                "reason": "Size too small",
                "back_to_stock": "1",
                "remarks": ""
            }
        ]
    }

Update return

Use the PUT parameter to update de status of a return. You can use any of the supported return states.

PUT 
https://api.returnless.com/returns/{return_id}?status=complete
RESPONSE 
{
    "result": true,
    "message": "Return updated successfully!"
}

Shipments endpoint

Basics

Use this endpoint to get Shipments in Returnless.

Get all shipments

GET 
https://api.returnless.com/shipments

Parameters

Parameter Description Example
per_page Set the amount of items that you want to show per page in your response. Choose a range between 1-200. 150
sort_order Use 'desc' to show newest items first (default) or use 'asc' to show oldest items first. asc
RESPONSE 
HTTP/1.1 200 OK

[
    {
        "tracking_number": "3STRVL987599921",
        "tracking_status_id": "1000",
        "tracking_status": "Ready to Send",
        "tracking_url": "https://jouw.postnl.nl/#!/track-en-trace/3STRVL987599921/NL/1234AB",
        "shipping_label_link": "https://www.returnless.com/shippinglabel/index/index?scid=3STRVL987599921&oid=371141&hash=a4d80bd0bd87b0ff2ef1f5b17bba557756cae676dbc6b01c0f12495de2b70c81&position=0",
        "return_id": "371141",
        "return": "RENL0005191022",
        "status": "processing",
        "reference": "1004",
        "order_id": "2598449381543",
        "return_date": "2022-01-20 11:52:42",
        "form": "5919",
        "customer_id": "58179",
        "customer_email": "pieter@returnless.com",
        "returned_products": [
            {
                "return_item_id": "1458191",
                "product_id": "1007",
                "qty_ordered": "1.0000",
                "qty_returned": "1.0000",
                "qty_received": "0.0000",
                "order_product_id": "153397",
                "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                "title_name": "Samsonite S'Cure Spinner 55",
                "model": "trvl-01598592",
                "article_code": "495398926",
                "cost": "87.50",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                "u_brand": "Samsonite",
                "ean": "890128492109899",
                "reason_id": "2",
                "reason": "Size too small",
                "back_to_stock": "1",
                "remarks": ""
            }
        ]
    }
]

Get single shipment

GET 
https://api.returnless.com/shipments/{tracking_number}
RESPONSE 
HTTP/1.1 200 OK

   [
       {
           "tracking_number": "3STRVL987599921",
           "tracking_status_id": "1000",
           "tracking_status": "Ready to Send",
           "tracking_url": "https://jouw.postnl.nl/#!/track-en-trace/3STRVL987599921/NL/1234AB",
           "shipping_label_link": "https://www.returnless.com/shippinglabel/index/index?scid=3STRVL987599921&oid=371141&hash=a4d80bd0bd87b0ff2ef1f5b17bba557756cae676dbc6b01c0f12495de2b70c81&position=0",
           "return_id": "371141",
           "return": "RENL0005191022",
           "status": "processing",
           "reference": "1004",
           "order_id": "2598449381543",
           "return_date": "2022-01-20 11:52:42",
           "form": "5919",
           "customer_id": "58179",
           "customer_email": "pieter@returnless.com",
           "returned_products": [
               {
                   "return_item_id": "1458191",
                   "product_id": "1007",
                   "qty_ordered": "1.0000",
                   "qty_returned": "1.0000",
                   "qty_received": "0.0000",
                   "order_product_id": "153397",
                   "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                   "title_name": "Samsonite S'Cure Spinner 55",
                   "model": "trvl-01598592",
                   "article_code": "495398926",
                   "cost": "87.50",
                   "images": [
                       {
                           "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                       }
                   ],
                   "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                   "u_brand": "Samsonite",
                   "ean": "890128492109899",
                   "reason_id": "2",
                   "reason": "Size too small",
                   "back_to_stock": "1",
                   "remarks": ""
               }
           ]
       }
   ]

Webhooks

With webhooks in Returnless, you can get push notifications when certain events happen. Use these webhooks to connect any platform to Returnless and be notified of changes in your Returnless account. Default webhook notifications are send every 15 minutes.

Authentication

You can find the API key in your portal. Go to Return Forms and find your API-key in the Webshop Integration tab:

  • API Key: Your API key. If you're unable to generate a new API-key, please contact us.
  • Webhook URL: Enter your desired with a leading slash ("https://www.yourdomain.com/webhook/returnless/index/").

When the webhook is triggered, we will make a POST request to your website using the URL entered in the Webhook URL configuration:

https://www.yourdomain.com/webhook/returnless/index/412123

To validate that it is us making the request to your server, we will add a returnless-signature in the header of the request:


returnless-signature: 4c7feb66d66873ec79c81cd8beb811f34e4ee37d9d24a407712b58049b08da9f

The signature is a HMAC-SHA256 encrypted hash of the Return ID, using your API key as the secret key. To authenticate, create your own encrypted hash of the Return ID in the URL using your API key as the secret key. If your signature is the same as the returnless-signature, you're good to go :)

Failures and retries

We expect you to give a 201 OK status code as a response. We ignore the content you send us. When we do not get a 201 OK status back from you, we consider the call as failed. We will retry to send the message 10 times in 3 hours. After 10 retries we delete the call from our queues.

New Return webhook

Subscribe to the New Return webhook to receive a notification when a return is created by one of your customers. It's very useful to connect this webhook to your e-commerce platform or Warehouse Management System (WMS). For example, you can use this webhook to make a list of all returns that are expected to arrive soon in your warehouse.

POST 
https://www.yourdomain.com/webhook/returnless/index/948191
REQUEST 
    {
        "action": "return_created",
        "return_id": "948191",
        "return": "RENL1641091121",
        "reference": "ORD000123",
        "order_id": "124006",
        "order_date": "2021-01-10 10:46:27",
        "return_date": "2021-01-20 11:52:42",
        "form": "5919",
        "customer_id": "58179",
        "customer_email": "pieter@returnless.com",
        "request_id": "481049",
        "shipping_description": "PostNL inleveren bij pakketpunt",
        "tracking_number": "3STRVL58192041",
        "tracking_status_id": "1000",
        "tracking_status": "Ready to Send",
        "tracking_url": "https://jouw.postnl.nl/track-and-trace/3STRVL58192041-NL-5611NV",
        "shipping_label_link": "https://www.returnless.com/shippinglabel/index/?scid=3SRLSS001989339&hash=hsFMhN544bhKD57wk9QDJxjsUJ",
        "billing_address": {
            "first_name": "Pieter",
            "last_name": "Post",
            "postcode": "5611NV",
            "country": "NL",
            "city": "Eindhoven",
            "address1": "PCzn Hooftlaan",
            "address2": "14",
            "addition": ""
        },
        "returned_products": [
            {
                "product_id": "1007",
                "qty_ordered": "1.0000",
                "qty_returned": "1.0000",
                "qty_received": "0.0000",
                "order_product_id": "153397",
                "name": "Samsonite S'Cure Spinner 55 navy blue capri",
                "title_name": "Samsonite S'Cure Spinner 55",
                "model": "trvl-01598592",
                "article_code": "495398926",
                "cost": "87.50",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/339033/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/samsonite-scure-spinner-55-navy-blue-capri.html",
                "u_brand": "Samsonite",
                "ean": "890128492109899",
                "reason_id": "2",
                "reason": "Size too small",
                "back_to_stock": "1",
                "remarks": ""
            },
            {
                "product_id": "1008",
                "qty_ordered": "2.0000",
                "qty_returned": "0.0000",
                "qty_received": "0.0000",
                "order_product_id": "153398",
                "name": "Eastpak x Havaianas Padded Pak'R Rugzak havaianas green",
                "title_name": "Eastpak x Havaianas Padded Pak'R Rugzak",
                "model": "trvl-1059819",
                "article_code": "EK000620C411001",
                "cost": "21.90",
                "images": [
                    {
                        "http_path": "https://media.travelshop-cdn.nl/product-square-680/362798/image.jpg"
                    }
                ],
                "url": "https://www.travelshop.nl/eastpak-x-havaianas-padded-pakr-rugzak-havaianas-green.html",
                "u_brand": "Eastpack",
                "ean": "5400879259557",
                "reason_id": "",
                "reason": "",
                "back_to_stock": "",
                "remarks": ""
            }
        ],
        "return_questions": [
            {
                "option_id": "46363",
                "label": "Please describe the damage.",
                "value": "There is a stain on the t-shirt."
            }
        ]
}