Fluent Commerce Logo
Docs
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 fees

16. 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 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 responseRequest 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/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 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

NAMETYPEDESCRIPTION
errorArrayArray of errors
messageStringAdditional information on the code Unauthorised | Bad Request | Forbidden | Not Found | Status 500 Error
codeStringStatus Code for the above messages 401 | 400 | 403 | 404 | 500

Fluent Commerce

Fluent Commerce