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 Order from the Retailer. A return can exist with or without the original order reference. If the original order 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 order 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: StringDescription:`{ "returnRef" : "554367" }`The return reference from the retailer.
2. orderRef
Type: StringDescription:`{ "orderRef" : "201607191462" }`The unique reference provided by the retailer.
3. orderId
Type: StringDescription:`{ "orderId" : "16425" }`The unique order id assigned by Fluent Commerce.
4. retailerId
Type: StringDescription:{ "retailerId" : "197" }`
`The retailer identifier assigned by Fluent Commerce.5. type
Type: StringDescription:`{ "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: ObjectDescription: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: ObjectDescription: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: objectDescription: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: ArrayDescription: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: ArrayDescription:1{
2"fulfilmentId": "5553633",
3"fulfilmentRef": "999878",
4"fulfilmentType": "R_RTDC",
5"status": "CREATED"
6}11. status
Type: StringDescription:` { "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: StringDescription:`{ "retailerId" : "197" }`13. createdOn
Type: DateTimeDescription:`{ "createdOn" : "2016-05-06T23:41:12.242Z" }`Date/time when the Return was created.
14. updatedOn
Type: DateTimeDescription:`{ "updatedOn" : "2016-06-23T07:58:58.000+0000" }`Date/time when the Return was last updated.15. totalReturnPrice
Type: DoubleDescription:`{ "totalReturnPrice" : "59.90" }`Total return value including shipping or click & collect fees16. sort
Type: StringDescription:` { "sort" : "createdOn DESC" }`Sorting options requested.Note: Currently default sorting "createdOn DESC” only supported.
`
`17. query
Type: StringDescription: Return Id, Order Reference or Customer Name searched forWhat you can do with Return
Create a Return
Create a Return in the Fluent Commerce system.POST:`/api/v4.1/return`Request and responseRequest parameters and sample1returnRequest {
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}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 }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/order/{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 Returns matching the search criteria.GET: /api/v4.1/return** Request and response**Request parameters and sample** Return request1returnRequest {
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}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 |