Returns

Attributes

If you provide the params idorder or idcustomer, the name and address fields will be copied from the linked order or customer if these fields are not given.

Name Type Required Description
idreturn integer generated Unique Picqer reference
idcustomer integer optional Linked to resource Customers
idorder integer optional Linked to resource Orders
idreturn_status integer required Linked to resource Return Statusses
idtemplate integer required Linked to resource Templates
returnid integer generated Per-account return number
name string optional Name of customer
contactname string optional Contact name of customer
address string optional Address rule of customer
address2 string optional Second address rule. Not accepted by all shipping providers
zipcode string optional ZIP code of customer
city string optional City of customer
country string optional Country of customer (needs to be ISO 3166 2-char code)
telephone string optional Telephone number of customer
emailaddress string optional Email address of customer
language string optional Language used for communication with customer, only 'nl' and 'en' are allowed
reference string optional Reference for customer, will be printed on invoice and pickling list
tracking_code string optional For your own reference, the tracking code of the package that you received from the customer
received_at datetime optional When you received the return from the customer, can be useful for determining when the money must be returned
returned_products array optional Products that the customer returns to you
replacement_products array optional Products that you sent the customer as replacement for the returned products

Get all returns

GET https://example.picqer.com/api/v1/returns
HTTP/1.1 200 OK [ { "idreturn": 392372, "idreturn_status": 82, "idcustomer": 294171, "idorder": 349469, "idtemplate": 2, "returnid": "R2017-1002", "name": "Franse Storm", "contactname": "prof. Luuk Henriquez", "address": "Albinusbaan 6304", "address2": null, "zipcode": "9590 YI", "city": "Poortvliet", "country": "NL", "telephone": null, "emailaddress": null, "language": "nl", "reference": null, "tracking_code": null, "received_at": null, "completed_at": null, "created_at": "2017-10-12 12:23:52", "updated_at": "2017-10-12 13:29:51" } ]

Filters

You can filter the returns with the following parameters. Add these filters as querystring parameters to the URL.

Attribute Description Example
search Search through the fields returnid, reference, customer name and customer contact name.
status Search for a specific idreturn_status, or use 'processing' or 'completed' to get all returns with statusses that are from the processing or completed type.

Get single return

For your convenience, details of return_status, customer, order, product and return_reason are included in the response of a single return. These are only settable via their corresponding id's.

GET https://example.picqer.com/api/v1/returns/{idreturn}
HTTP/1.1 200 OK { "idreturn": 392372, "idreturn_status": 82, "idcustomer": 294171, "idorder": 349469, "idtemplate": 2, "returnid": "R2017-1002", "name": "Franse Storm", "contactname": "prof. Luuk Henriquez", "address": "Albinusbaan 6304", "address2": null, "zipcode": "9590 YI", "city": "Poortvliet", "country": "NL", "telephone": null, "emailaddress": null, "language": "nl", "reference": null, "tracking_code": null, "received_at": null, "completed_at": null, "created_at": "2017-10-12 12:23:52", "updated_at": "2017-10-12 13:29:51", "return_status": { "idreturn_status": 82, "name": "Received", "default": true, "completed": false, "color": "1db0de", "created_at": "2017-06-08 15:42:24", "updated_at": "2017-06-08 15:42:24" }, "customer": { "idcustomer": 294171, "customerid": "10", "name": "Franse Storm", "contactname": "prof. Luuk Henriquez M" }, "order": { "idorder": 349469, "orderid": "O2017-1030", "reference": null, "created_at": "2017-10-10 09:39:44" }, "returned_products": [ { "idreturn_product": 875645, "idreturn": 392372, "idreturn_reason": 8273, "idproduct": 1105257, "idwarehouse": null, "price": 123.45, "amount": 1, "status": "expected", "changeable": true, "product": { "idproduct": 1105257, "image_url": null, "productcode": "59dc793c21bac", "name": "Philips Chronoplay 28" }, "return_reason": { "idreturn_reason": 8273, "name": "Dead on arrival" } }, { "idreturn_product": 875646, "idreturn": 392372, "idreturn_reason": 8273, "idproduct": 1105258, "idwarehouse": null, "price": 29.92, "amount": 3, "status": "received", "changeable": true, "product": { "idproduct": 1105258, "image_url": null, "productcode": "59dc793c64ca4", "name": "Sony Walkman 2992" }, "return_reason": { "idreturn_reason": 8273, "name": "Dead on arrival" } } ], "replacement_products": [ { "idreturn_product_replacement": 22231, "idreturn": 392372, "idproduct": 1105250, "idpicklist": null, "price": 460.54, "amount": 1, "status": "concept", "changeable": true, "product": { "idproduct": 1105250, "image_url": null, "productcode": "OV230383", "name": "Knorr Eco Drive" } } ], "totals": { "returned_products_count": 4, "returned_products_value": 402.21, "replacement_products_count": 1, "replacement_products_value": 460.54, "days_after_order_shipped": null } }

Create new return

Returns can be created including the returned and replacement products. These products can also be attached later.

POST https://example.picqer.com/api/v1/returns
{ "idreturn_status": 1, "idtemplate": 2, "name": "John Hendriks", "contactname": null, "address": "Dorpsstraat 304", "address2": null, "zipcode": "8272 EM", "city": "Vlissingen", "country": "NL", "telephone": null, "emailaddress": "john@example.org", "reference": "Order 23992", "returned_products": [ { "idreturn_reason": 1, "idproduct": 1105257, "amount": 1 }, { "idreturn_reason": 1, "idproduct": 1105258, "amount": 1 } ], "replacement_products": [ { "idproduct": 1105250, "amount": 1 } ] }
HTTP/1.1 201 Created { "idreturn": 4, "idreturn_status": 1, "idcustomer": null, "idorder": null, "idtemplate": 2, "returnid": "R2017-1003", "name": "John Hendriks", "contactname": null, "address": "Dorpsstraat 304", "address2": null, "zipcode": "8272 EM", "city": "Vlissingen", "country": "NL", "telephone": null, "emailaddress": "john@example.org", "language": null, "reference": "Order 23992", "tracking_code": null, "received_at": null, "completed_at": null, "created_at": "2017-10-13 11:29:09", "updated_at": "2017-10-13 11:29:09", "return_status": { "idreturn_status": 1, "name": "Received", "default": true, "completed": false, "color": "1db0de", "created_at": "2017-06-08 15:42:24", "updated_at": "2017-06-08 15:42:24" }, "customer": null, "order": null, "returned_products": [ { "idreturn_product": 11, "idreturn": 4, "idreturn_reason": 1, "idproduct": 1105257, "idwarehouse": null, "price": 0, "amount": 1, "status": "expected", "changeable": true, "product": { "idproduct": 1105257, "image_url": null, "productcode": "59dc793c21bac", "name": "Philips Candle 2992" }, "return_reason": { "idreturn_reason": 1, "name": "Unknown" } }, { "idreturn_product": 12, "idreturn": 4, "idreturn_reason": 1, "idproduct": 1105258, "idwarehouse": null, "price": 0, "amount": 1, "status": "expected", "changeable": true, "product": { "idproduct": 1105258, "image_url": null, "productcode": "59dc793c64ca4", "name": "Philips Candle 2991" }, "return_reason": { "idreturn_reason": 1, "name": "Unknown" } } ], "replacement_products": [ { "idreturn_product_replacement": 3, "idreturn": 4, "idproduct": 1105250, "idpicklist": null, "price": 0, "amount": 1, "status": "concept", "changeable": true, "product": { "idproduct": 1105250, "image_url": null, "productcode": "OV230383", "name": "Knorr Eco Drive" } } ], "totals": { "returned_products_count": 2, "returned_products_value": 0, "replacement_products_count": 1, "replacement_products_value": 0, "days_after_order_shipped": null } }

Update return

You can change the return after you created it. You can only change the meta parameters of the return with this call. See examples below for adding and removing returned products or replacement products.

PUT https://example.picqer.com/api/v1/returns/{idreturn}
{ "name": "Professor Hendriks", "emailaddress": "hendriks@example.org" }
HTTP/1.1 200 OK { "idreturn": 4, "idreturn_status": 1, "idcustomer": null, "idorder": null, "idtemplate": 2, "returnid": "R2017-1003", "name": "Professor Hendriks", ...

Returned products

You can use the endpoint /api/v1/returns/{idreturn}/returned_products to only get the details of returned products for a return.

To add a new product to an existing return, you can POST that product with the following example.

You can only add 1 product per call. Required fields are: idreturn_reason, idproduct, price and amount.

POST https://example.picqer.com/api/v1/returns/{idreturn}/returned_products
{ "idreturn_reason": 1, "idproduct": 1105257, "price": 12.95, "amount": 1 }
HTTP/1.1 200 OK { "idreturn_product": 13, "idreturn": 4, "idreturn_reason": 1, "idproduct": 1105257, "idwarehouse": null, "price": 12.95, "amount": 1, "status": "expected", "changeable": true, "product": { "idproduct": 1105257, "image_url": null, "productcode": "59dc793c21bac", "name": "Philips Candle 2991" }, "return_reason": { "idreturn_reason": 1, "name": "Unknown" } }

To update a returned product, you can send a PUT request to endpoint /api/v1/returns/{idreturn}/returned_products/{idreturn_product} to update price, amount or reason.

To delete a returned product, send a DELETE request to endpoint /api/v1/returns/{idreturn}/returned_products/{idreturn_product}.

Deletes and updates can only be done when the parameter changable is true.

Replacement products

You can use the endpoint /api/v1/returns/{idreturn}/replacement_products to only get the details of replacement products for a return.

To add a new product to an existing return, you can POST that product with the following example.

You can only add 1 product per call. Required fields are: idproduct, price and amount.

POST https://example.picqer.com/api/v1/returns/{idreturn}/replacement_products
{ "idproduct": 1105257, "price": 12.95, "amount": 1 }
HTTP/1.1 200 OK { "idreturn_product_replacement": 5, "idreturn": 4, "idproduct": 1105257, "idpicklist": null, "price": 12, "amount": 1, "status": "concept", "changeable": true, "product": { "idproduct": 1105257, "image_url": null, "productcode": "59dc793c21bac", "name": "Philips Candle 2991" } }

To update a replacement product, you can send a PUT request to endpoint /api/v1/returns/{idreturn}/replacement_products/{idreturn_product_replacement} to update price or amount.

To delete a replacement product, send a DELETE request to endpoint /api/v1/returns/{idreturn}/replacement_products/{idreturn_product_replacement}.

Deletes and updates can only be done when the parameter changable is true.

Get logbook and comments

The logs of a return are all the changes and comments on a return, as shown on the side of a return in the Picqer web app

Possible types for logs are: created, comment, status_changed, completed, received_products and created_picklist

GET https://example.picqer.com/api/v1/returns/{idreturn}/logs
HTTP/1.1 200 OK [ { "idreturn_log": 14, "idreturn_status": 1, "iduser": 424, "type": "received_products", "message": "13 x \u0022Nikon CAS Lumix \u0022 marked as expected", "notified_customer": false, "created_at": "2017-07-18 10:20:48", "updated_at": "2017-07-18 10:20:48", "return_status": { "idreturn_status": 1, "name": "Received", "color": "1db0de" }, "user": { "iduser": 424, "name": "Casper Bakker" } }, { "idreturn_log": 13, "idreturn_status": 1, "iduser": 424, "type": "received_products", "message": "13 x \u0022Nikon CAS Lumix \u0022 gemarkeerd als ontvangen", "notified_customer": false, "created_at": "2017-07-18 10:20:40", "updated_at": "2017-07-18 10:20:40", "return_status": { "idreturn_status": 1, "name": "Received", "color": "1db0de" }, "user": { "iduser": 424, "name": "Casper Bakker" } }, { "idreturn_log": 10, "idreturn_status": 1, "iduser": null, "type": "created", "message": null, "notified_customer": false, "created_at": "2017-07-14 12:21:13", "updated_at": "2017-07-14 12:21:13", "return_status": { "idreturn_status": 1, "name": "Received", "color": "1db0de" }, "user": null } ]

Add comment or change status

To add a comment or to change the status, or both, you can POST to the logs endpoint.

Name Type Required Description
idreturn_status integer optional Status that this return needs to get. If it is not provided, the status will remain the same
message string optional A comment or note on the return
notify_customer boolean optional, default: false If true, customer will receive a email with the update status or comment. Only if a valid email address is provided in the return
POST https://example.picqer.com/api/v1/returns/{idreturn}/logs
{ "idreturn_status": 1, "message": "Return label provided to customer", "notify_customer": true }
HTTP/1.1 200 OK { "idreturn_log": 24, "idreturn_status": 1, "iduser": 424, "type": "comment", "message": "Return label provided to customer", "notified_customer": true, "created_at": "2017-10-13 11:59:33", "updated_at": "2017-10-13 11:59:33", "return_status": { "idreturn_status": 1, "name": "Received", "color": "1db0de" }, "user": { "iduser": 424, "name": "Casper Bakker" } }
Read more Backorders