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 Statuses |
| 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 line of customer |
| address2 | string | optional | Second address line. Not accepted by all shipping providers |
| zipcode | string | optional | ZIP code of customer |
| city | string | optional | City of customer |
| region | string | optional | Region, state or province 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 |
| idfulfilment_customer | integer | optional | Only for Picqer Fulfilment: Linked to belonging fulfilment customer |
| returned_products | array | optional | Products that the customer returns to you |
| returned_products.idreturn_reason | integer | required | Reason for returning the product. Linked to resource Return Reasons |
| returned_products.idproduct | integer | required | The returned product. Linked to resource Products |
| returned_products.price | float | required | The price (VAT excluded) of the returned product |
| returned_products.amount | integer | required | The returned amount of the product |
| 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",
"region": null,
"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"
}
]
This endpoint uses pagination.
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 statuses that are from the processing or completed type. | |
| emailaddress | Get the returns that have this value as email address. | |
| created_after | Get the returns that are created since this date and time. | 2020-10-26 00:00:00 |
| updated_after | Get the returns that are changed since this date and time. | 2020-10-26 00:00:00 |
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",
"region": null,
"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,
"idlocation": 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"
},
"location": null
},
{
"idreturn_product": 875646,
"idreturn": 392372,
"idreturn_reason": 8273,
"idproduct": 1105258,
"idwarehouse": 561,
"idlocation": 6516,
"price": 29.92,
"amount": 3,
"status": "added_to_stock",
"changeable": true,
"product": {
"idproduct": 1105258,
"image_url": null,
"productcode": "59dc793c64ca4",
"name": "Sony Walkman 2992"
},
"return_reason": {
"idreturn_reason": 8274,
"name": "Wrong size"
},
"location": {
"idlocation": 6516,
"idwarehouse": 561,
"parent_idlocation": 6510,
"name": "B.5.6.1",
"remarks": null,
"unlink_on_empty": false,
"location_type": {
"idlocation_type": 1684,
"name": "Standaard",
"default": true,
"color": "#0000f0"
},
"is_bulk_location": false,
"is_exclusive_location": false,
"type": "location"
}
}
],
"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",
"region": null,
"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",
"region": null,
"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"
}
}
Receive returned products
You can register what happend with the returned products with this endpoint.
The status field can have the values: expected, received, added_to_stock, unsalable.
The status added_to_stock will add the products back to the stock. It is mandatory to provide idwarehouse for this status. You can specify the location to use by passing an idlocation. If no idlocation is passed the stock will be added to "No specific location".
POST
https://example.picqer.com/api/v1/returns/{idreturn}/receive
{
"idwarehouse": 1,
"return_products": [
{
"idreturn_product": 21,
"idreturn_status": 1,
"status": "added_to_stock",
"idlocation": 1
},
{
"idreturn_product": 22,
"idreturn_status": 1,
"status": "received"
},
{
"idreturn_product": 23,
"idreturn_status": 1,
"status": "unsalable"
}
]
}
HTTP/1.1 200 OK
{
"idreturn": 37,
"idreturn_status": 2,
"idcustomer": null,
"idorder": 3,
"idtemplate": 1,
"returnid": "R2019-1000",
"name": "Jeroen Diederik",
"contactname": null,
"address": "Lange Laan 12",
"address2": null,
"zipcode": "2928 EM",
"city": "Lelystad",
"region": null,
"country": "NL",
"full_address": "Jeroen Diederik\nLange Laan 12\n2928 EM Lelystad\nNederland",
"telephone": null,
"emailaddress": null,
"language": "nl",
"reference": null,
"tracking_code": null,
"received_at": null,
"completed_at": null,
"created_at": "2019-02-22 09:43:51",
"updated_at": "2019-02-22 09:46:42"
}
Comments
Comments are supported on returns.
Read more Backorders
