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


Fluent Commerce

Fluent Commerce