Return API
Essential knowledge
Author:
Fluent Commerce
Changed on:
3 July 2024
Overview
A return is a customer's request to send back one or more items against an from the Retailer. A return can exist with or without the original reference. If the original reference exists, the return can contain the details of the returned items, the reasons, and the amount to be refunded. A return also could represent items within an original that could not be fulfilled or has been canceled by the customer and requires a subsequent refund. Through the type of return, we can identify the context of the return, i.e., if it is a customer return, cannot fulfill or cancel.
Key points
- The properties are available in the Return object
- This Return object can be updated and retrieved through the API
Return Properties
Below properties are available in the Return object which can be updated and retrieved through the APIs in this document.
1. returnRef
Type: String
Description:
`{ "returnRef" : "554367" }`
The return reference from the retailer.
2. orderRef
Type: String
Description:
`{ "orderRef" : "201607191462" }`
The unique reference provided by the retailer.
3. orderId
Type: String
Description:
`{ "orderId" : "16425" }`
The unique id assigned by Fluent Commerce.
4. retailerId
Type: String
Description:
{ "retailerId" : "197" }`
`
The retailer identifier assigned by Fluent Commerce.
5. type
Type: String
Description:
`{ "type" : "CUSTOMER_RETURN" }`
The type of return. Possible values are:
- CUSTOMER_RETURN - A customer initiated return.
- CANCELLATION - The order was cancelled using Admin Console and a full refund has been initiated.
- CANNOT_FULFIL - The original order contained items that couldn't be fulfilled so a refund has been initiated.
6. customer
Type: Object
Description:
1{
2"customerId": "5647547",
3"customerRef": "34562829",
4"email": "john@gmail.com",
5"firstName": "John",
6"lastName": "Smith",
7"mobile": "0407000111"
8}7. fulfilmentChoice
Type: Object
Description:
1{
2"preferredLocationRef": "SHA080",
3"fulfilmentType": "R_RTDC",
4"fulfilmentPrice": "7.90",
5"fulfilmentTaxPrice": "0.80",
6"currency": "AUD",
7"address": "<see example below>"
8}8. address
Type: object
Description:
1{
2"city": "Sydney",
3"companyName": "Seed Heritage",
4"country": "Aus",
5"locationRef": "2038",
6"name": "",
7"postcode": "2000",
8"state": "NSW",
9"street": "123 Pitt St"
10}9. items
Type: Array
Description:
1{
2"skuId":"368961",
3"skuRef":"1022096-578-2-3-se",
4"skuPrice":19.99,
5"skuTaxPrice":null,
6"taxType":null,
7"currency":null,
8"returnQty":1,
9"returnReason":"Damaged",
10"returnCondition":"0"
11}10. fulfilments
Type: Array
Description:
1{
2"fulfilmentId": "5553633",
3"fulfilmentRef": "999878",
4"fulfilmentType": "R_RTDC",
5"status": "CREATED"
6}11. status
Type: String
Description:
` { "status" : "LODGED" }`
Current status of the return. Possible values are:
- CREATED - Return created
- BOOKED - Customer return booked.
- LODGED - Automatic refund strategy has been initiated i.e. Original order is single tender type and payment gateway is integrated.
- PENDING RETURN - User initiated refund strategy has been initiated.
i.e. Original order includes more than one tender type and/or payment gateway is not integrated.
Return can also move to this state if the return transaction is declined by the payment gateway. - COMPLETE - Refund processed.
12. retailerId
Type: String
Description:
`{ "retailerId" : "197" }`
13. createdOn
Type: DateTime
Description:
`{ "createdOn" : "2016-05-06T23:41:12.242Z" }`
Date/time when the Return was created.
14. updatedOn
Type: DateTime
Description:
`{ "updatedOn" : "2016-06-23T07:58:58.000+0000" }`
Date/time when the Return was last updated.
15. totalReturnPrice
Type: Double
Description:
`{ "totalReturnPrice" : "59.90" }`
Total return value including shipping or fees
16. sort
Type: String
Description:
` { "sort" : "createdOn DESC" }`
Sorting options requested.
Note: Currently default sorting "createdOn DESC” only supported.`
`
17. query
Type: String
Description: Return Id, Reference or Customer Name searched for
What you can do with Return
Create a Return
Create a Return in the Fluent Commerce system.
POST: `/api/v4.1/return`
Request and response
Request parameters and sample
1returnRequest {
2 customer (Object, compulsory),
3
4 customer {
5 customerId (string, optional),
6 customerRef (string, optional)
7 email (string, compulsory),
8 firstName (string, optional),
9 lastName (string, optional),
10 mobile (string, optional)
11 }
12
13 fulfilmentChoice (Object, optional),
14
15 fulfilmentChoice {
16 address (object, optional),
17 currency (string, optional),
18 fulfilmentPrice (double, optional),
19 fulfilmentTaxPrice (double, optional),
20 fulfilmentType (string, optional),
21 preferredLocationRef (string, optional)
22 }
23
24 fulfilments (array, optional),
25
26 fulfilments {
27 fulfilmentId (string, optional),
28 fulfilmentRef (string, optional),
29 fulfilmentType (string, optional) = 'R_RTDC', 'R_RTS',
30 status (string, optional) = 'CREATED', 'COMPLETE', 'ARRIVED'
31
32 items (array, optional),
33
34 items {
35 currency (string, optional),
36 returnCondition (string, optional),
37 returnQty (integer, optional),
38 returnReason (string, optional),
39 skuId (string, optional),
40 skuPrice (double, optional),
41 skuRef (string, compulsory),
42 skuTaxPrice (double, optional),
43 taxType (string, optional) = 'GST', 'VAT', 'EXCLTAX'
44
45 orderId (string, optional),
46 orderRef (string, optional),
47 retailerId (string, compulsory),
48 returnRef (string, optional),
49 status (string, optional) = 'CREATED', 'BOOKED', 'LODGED', 'PENDING_REFUND', 'COMPLETE',
50 type (string, compulsory) = 'CUSTOMER_RETURN', 'CANNOT_FULFIL', 'CANCELLATION'
51 }1{
2 "orderRef":"201607191462",
3 "orderId":"427331",
4 "type":"CUSTOMER_RETURN",
5 "retailerId":433,
6 "customer":{
7 "customerId":903674,
8 "customerRef":"38189566",
9 "firstName":"swathi",
10 "lastName":null,
11 "mobile":null,
12 "email":"eorxy@parcelpoint.com.au"
13 },
14 "items":[
15 {
16 "skuId":"368961",
17 "skuRef":"1022096-578-2-3-se",
18 "skuPrice":19.99,
19 "skuTaxPrice":null,
20 "taxType":null,
21 "currency":null,
22 "returnQty":1,
23 "returnReason":"Damaged",
24 "returnCondition":"0"
25 },
26 {
27 "skuId":"368961",
28 "skuRef":"1022096-578-2-3-se",
29 "skuPrice":19.99,
30 "skuTaxPrice":null,
31 "taxType":null,
32 "currency":null,
33 "returnQty":1,
34 "returnReason":"Damaged",
35 "returnCondition":"0"
36 }
37 ],
38 "fulfilmentChoice":{
39 "preferredLocationRef":"SHA080",
40 "fulfilmentType":"R_RTDC",
41 "address":{
42 "locationRef":"SHA080"
43 }
44 }
45}Response Parameters and sample
1SuccessMessageResponse {
2 id (integer, optional)
3 }1{
2 "id":"427323"
3}
View Return via returnId
Retrieve details of the Return using returnId.
GET: `/api/v4.1/return/{returnId}`
** Request and response **
Request parameters and sample
** Return request
`/api/v4.1/return/{returnId}`
** Example request
`/api/v4.1/return/5463`
Response Parameters and sample
** Return response
1returnResponse {
2
3 customer (Object),
4
5 customer {
6 customerId (string),
7 customerRef (string)
8 email (string),
9 firstName (string),
10 lastName (string),
11 mobile (string)
12 }
13
14 fulfilmentChoice (Object),
15
16 fulfilmentChoice {
17 address (object),
18 city (string),
19 companyName (string),
20 country (string),
21 locationRef (string),
22 name (string),
23 postcode (string),
24 state (string),
25 street (string)
26 currency (string),
27
28 fulfilmentPrice (double),
29 fulfilmentTaxPrice (double),
30 fulfilmentType (string),
31 preferredLocationRef (string)
32 }
33
34 fulfilments (array),
35
36 fulfilments {
37 fulfilmentId (string),
38 fulfilmentRef (string),
39 fulfilmentType (string) = 'R_RTDC', 'R_RTS',
40 status (string) = 'CREATED', 'COMPLETE', 'ARRIVED'
41 items (array),
42
43 items {
44 currency (string),
45 returnCondition (string),
46 returnQty (integer),
47 returnReason (string),
48 skuId (string),
49 skuPrice (double),
50 skuRef (string),
51 skuTaxPrice (double),
52 taxType (string) = 'GST', 'VAT', 'EXCLTAX'
53
54 orderId (string),
55 orderRef (string),
56 retailerId (string),
57 returnRef (string),
58 status (string) = 'CREATED', 'BOOKED', 'LODGED', 'PENDING_REFUND', 'COMPLETE',
59 type (string) = 'CUSTOMER_RETURN', 'CANNOT_FULFIL', 'CANCELLATION',
60 createdOn (DateTime)
61 }Example Response,
1{
2 "orderRef":"201607191462",
3 "orderId":"427331",
4 "returnRef":"87f996fe-f915-4e8c-bcde-275c5ca9cb4d",
5 "retailerId":"433",
6 "type":"CUSTOMER_RETURN",
7 "status":"PENDING_REFUND",
8 "customer":{
9 "customerId":903674,
10 "customerRef":"38189566",
11 "firstName":"swathi",
12 "lastName":null,
13 "email":"eorxy@parcelpoint.com.au",
14 "mobile":null
15 },
16 "items":[
17 {
18 "skuId":"368961",
19 "skuRef":"1022096-578-2-3-se",
20 "skuPrice":19.99,
21 "skuTaxPrice":null,
22 "taxType":null,
23 "currency":null,
24 "returnQty":1,
25 "returnReason":"Damaged",
26 "returnCondition":"0"
27 },
28 {
29 "skuId":"368961",
30 "skuRef":"1022096-578-2-3-se",
31 "skuPrice":19.99,
32 "skuTaxPrice":null,
33 "taxType":null,
34 "currency":null,
35 "returnQty":1,
36 "returnReason":"Damaged",
37 "returnCondition":"0"
38 }
39 ],
40 "fulfilmentChoice":{
41 "fulfilmentType":"R_RTDC",
42 "preferredLocationRef":"SHA080",
43 "fulfilmentPrice":null,
44 "fulfilmentTaxPrice":null,
45 "currency":null,
46 "address":{
47 "locationRef":"SHA080",
48 "companyName":"Seed Heritage Camberwell",
49 "name":null,
50 "street":"598 Burke Road",
51 "city":"Camberwell",
52 "postcode":"3124",
53 "state":"VIC",
54 "country":"Australia"
55 }
56 },
57 "fulfilments":[
58 {
59 "fulfilmentId":"244188",
60 "fulfilmentRef":null,
61 "status":"COMPLETE",
62 "fulfilmentType":"R_RTDC"
63 }
64 ],
65 "createdOn":"2016-07-20T00:40:34.845+0000"
66}
View Return via orderId
Retrieve details of the Return using orderId.
GET: /api/v4.1//{orderId}/return
** Request and response **
Request parameters and sample
** Return request
`/api/v4.1/order/{orderId}/return`
** Example request
`/api/v4.1/order/553638/return`
Response Parameters and sample
1returnResponse {
2 orderId (string),
3 orderRef (string),
4 retailerId (string),
5 returns (array),
6
7 returns {
8 createdOn (DateTime),
9 customer (Object),
10
11 customer {
12 customerId (string),
13 customerRef (string)
14 email (string),
15 firstName (string),
16 lastName (string),
17 mobile (string)
18 }
19
20 fulfilmentChoice (Object),
21
22 fulfilmentChoice {
23 address (object),
24 city (string),
25 companyName (string),
26 country (string),
27 locationRef (string),
28 name (string),
29 postcode (string),
30 state (string),
31 street (string)
32
33 currency (string),
34 fulfilmentPrice (double),
35 fulfilmentTaxPrice (double),
36 fulfilmentType (string),
37 preferredLocationRef (string)
38
39 fulfilments (array),
40
41 fulfilments {
42 fulfilmentId (string),
43 fulfilmentRef (string),
44 fulfilmentType (string) = 'R_RTDC', 'R_RTS',
45 status (string) = 'CREATED', 'COMPLETE', 'ARRIVED'
46
47 items (array),
48
49 items {
50 currency (string),
51 returnCondition (string),
52 returnQty (integer),
53 returnReason (string),
54 skuId (string),
55 skuPrice (double),
56 skuRef (string),
57 skuTaxPrice (double),
58 taxType (string) = 'GST', 'VAT', 'EXCLTAX'
59
60
61 returnId (string),
62 returnRef (string),
63 status (string) = 'CREATED', 'BOOKED', 'LODGED', 'PENDING_REFUND', 'COMPLETE',
64 type (string) = 'CUSTOMER_RETURN', 'CANNOT_FULFIL', 'CANCELLATION'
65
66 }1{
2 "orderRef":"201607191471",
3 "orderId":"427340",
4 "retailerId":"433",
5 "returns":[
6 {
7 "returnId":"427341",
8 "returnRef":"4c9b2be8-969a-4d95-a20a-8cb017e5ade2",
9 "type":"CANNOT_FULFIL",
10 "status":"CREATED",
11 "customer":{
12 "customerId":903674,
13 "customerRef":"38189566",
14 "firstName":"swathi",
15 "lastName":null,
16 "email":"eorxy@parcelpoint.com.au",
17 "mobile":null
18 },
19 "items":[
20 {
21 "skuId":"368961",
22 "skuRef":"1022096-578-2-3-se",
23 "skuPrice":19.99,
24 "skuTaxPrice":null,
25 "taxType":null,
26 "currency":null,
27 "returnQty":1,
28 "returnReason":"CANNOT_FULFIL",
29 "returnCondition":"CANNOT_FULFIL"
30 }
31 ],
32 "fulfilmentChoice":null,
33 "fulfilments":[
34 {
35 "fulfilmentId":"123232",
36 "fulfilmentRef":"4-ie-erwerwe-1234",
37 "fulfilmentType": "R_RTDC",
38 "status": "ARRIVED"
39 }
40 ],
41 "createdOn":"2016-07-19T06:48:44.469+0000"
42 }
43 ]
44}Search Returns
Retrieve a list of matching the search criteria.
GET: /api/v4.1/return
** Request and response**
Request parameters and sample
** Return request
1returnRequest {
2
3 retailerId (string, compulsory),
4 start (integer, optional),
5 count (integer, optional),
6 sort (string, optional) = 'createdOn DESC',
7 query (string, optional) = returnId, customerName, orderRef,
8 type (string, optional) = 'CUSTOMER_RETURN', 'CANNOT_FULFIL', 'CANCELLATION' { multiple can be passed},
9 status (string, optional) = 'CREATED', 'BOOKED', 'LODGED', 'PENDING_REFUND', 'COMPLETE' { multiple can be passed}
10}1{
2 "retailerId":"197",
3 "start":"1",
4 "count":"10",
5 "sort":"createdOn DESC",
6 "query":"",
7 "type":"CUSTOMER_RETURN",
8 "status":"CREATED"
9}Response Parameters and sample
** Return response
1returnResponse {
2
3 start (integer),
4 count (integer),
5 total (integer),
6 retailerId (string),
7 results (integer):[
8 {
9 orderId (string),
10 orderRef (string),
11 customerId (string),
12 customerFirstName (string),
13 customerLastName (string),
14 totalReturnPrice (string),
15 currency (string),
16 createdOn (DateTime),
17 type (string) = 'CUSTOMER_RETURN', 'CANNOT_FULFIL', 'CANCELLATION',
18 status (string) = 'CREATED', 'BOOKED', 'LODGED', 'PENDING_REFUND', 'COMPLETE' ,
19 preferredLocationRef (string),
20 returnId (string),
21 returnRef (string)
22 }
23 ]
24 }1{
2 "start":1,
3 "count":10,
4 "total":226,
5 "retailerId":"433",
6 "results":[
7 {
8 "orderId":"427331",
9 "orderRef":"201607191462",
10 "customerId":"903674",
11 "customerFirstName":"swathi",
12 "customerLastName":null,
13 "totalReturnPrice":39.98,
14 "currency":null,
15 "createdOn":"2016-07-20T00:40:34.845+0000",
16 "type":"CUSTOMER_RETURN",
17 "status":"PENDING_REFUND",
18 "preferredLocationRef":"SHA080",
19 "returnId":"427342",
20 "returnRef":"87f996fe-f915-4e8c-bcde-275c5ca9cb4d"
21 },
22 {
23 "orderId":"427340",
24 "orderRef":"201607191471",
25 "customerId":"903674",
26 "customerFirstName":"swathi",
27 "customerLastName":null,
28 "totalReturnPrice":19.99,
29 "currency":null,
30 "createdOn":"2016-07-19T06:48:44.469+0000",
31 "type":"CANNOT_FULFIL",
32 "status":"CREATED",
33 "preferredLocationRef":null,
34 "returnId":"427341",
35 "returnRef":"4c9b2be8-969a-4d95-a20a-8cb017e5ade2"
36 },
37 {
38 "orderId":"427323",
39 "orderRef":"1171615111",
40 "customerId":"903677",
41 "customerFirstName":"nick",
42 "customerLastName":"yaw",
43 "totalReturnPrice":19.99,
44 "currency":null,
45 "createdOn":"2016-07-19T03:11:20.291+0000",
46 "type":"CANNOT_FULFIL",
47 "status":"CREATED",
48 "preferredLocationRef":null,
49 "returnId":"427324",
50 "returnRef":"c74cb5ef-415f-4478-b0a3-2c9c593fb51c"
51 },
52 {
53 "orderId":"427316",
54 "orderRef":"201607131103",
55 "customerId":"903674",
56 "customerFirstName":"swathi",
57 "customerLastName":null,
58 "totalReturnPrice":39.98,
59 "currency":null,
60 "createdOn":"2016-07-13T01:27:12.380+0000",
61 "type":"CUSTOMER_RETURN",
62 "status":"PENDING_REFUND",
63 "preferredLocationRef":"SHA114",
64 "returnId":"427318",
65 "returnRef":"559de85a-d9a2-43ef-ba39-bed9220d1b2f"
66 },
67 {
68 "orderId":"427316",
69 "orderRef":"201607131103",
70 "customerId":"903674",
71 "customerFirstName":"swathi",
72 "customerLastName":null,
73 "totalReturnPrice":39.98,
74 "currency":null,
75 "createdOn":"2016-07-13T01:26:39.304+0000",
76 "type":"CUSTOMER_RETURN",
77 "status":"PENDING_REFUND",
78 "preferredLocationRef":"SHA114",
79 "returnId":"427317",
80 "returnRef":"87f3a0fa-3fb0-4b64-ae5c-c58d16ec53a1"
81 },
82 {
83 "orderId":"427314",
84 "orderRef":"201607131102",
85 "customerId":"903674",
86 "customerFirstName":"swathi",
87 "customerLastName":null,
88 "totalReturnPrice":39.98,
89 "currency":null,
90 "createdOn":"2016-07-13T01:10:19.793+0000",
91 "type":"CANNOT_FULFIL",
92 "status":"CREATED",
93 "preferredLocationRef":null,
94 "returnId":"427315",
95 "returnRef":"178dec57-482c-4321-a380-2d19fffb1da0"
96 },
97 {
98 "orderId":"427310",
99 "orderRef":"201607131101",
100 "customerId":"903674",
101 "customerFirstName":"swathi",
102 "customerLastName":null,
103 "totalReturnPrice":19.99,
104 "currency":null,
105 "createdOn":"2016-07-13T01:08:33.505+0000",
106 "type":"CUSTOMER_RETURN",
107 "status":"PENDING_REFUND",
108 "preferredLocationRef":"SHA114",
109 "returnId":"427312",
110 "returnRef":"42ce0208-0c71-4a21-8e81-736d9b8febaa"
111 },
112 {
113 "orderId":"427310",
114 "orderRef":"201607131101",
115 "customerId":"903674",
116 "customerFirstName":"swathi",
117 "customerLastName":null,
118 "totalReturnPrice":19.99,
119 "currency":null,
120 "createdOn":"2016-07-13T01:08:00.147+0000",
121 "type":"CUSTOMER_RETURN",
122 "status":"PENDING_REFUND",
123 "preferredLocationRef":"SHA114",
124 "returnId":"427311",
125 "returnRef":"4679fb8a-ee16-4adf-a3ba-6847ab4d95d9"
126 },
127 {
128 "orderId":"427306",
129 "orderRef":"201607130951",
130 "customerId":"903674",
131 "customerFirstName":"swathi",
132 "customerLastName":null,
133 "totalReturnPrice":39.98,
134 "currency":null,
135 "createdOn":"2016-07-13T00:22:15.894+0000",
136 "type":"CANNOT_FULFIL",
137 "status":"CREATED",
138 "preferredLocationRef":null,
139 "returnId":"427307",
140 "returnRef":"648dfb81-8c42-4200-a5fb-7cdc28394544"
141 },
142 {
143 "orderId":"427302",
144 "orderRef":"201607130950",
145 "customerId":"903674",
146 "customerFirstName":"swathi",
147 "customerLastName":null,
148 "totalReturnPrice":39.98,
149 "currency":null,
150 "createdOn":"2016-07-13T00:20:22.007+0000",
151 "type":"CANNOT_FULFIL",
152 "status":"CREATED",
153 "preferredLocationRef":null,
154 "returnId":"427305",
155 "returnRef":"878812ae-0fb4-4a44-a849-b5dd5aa81fc0"
156 }
157 ],
158 "query":null,
159 "sort":"createdOn DESC",
160 "status":[
161],
162 "type":[
163]
164}Response on Failures
NAME | TYPE | DESCRIPTION |
error | Array | Array of errors |
message | String | Additional information on the code Unauthorised | Bad Request | Forbidden | Not Found | Status 500 Error |
code | String | Status Code for the above messages 401 | 400 | 403 | 404 | 500 |
