Docs
Changed on:
18 Dec 2023
The Returns Field Component provides an end user experience for creating Returns through an OMX web application. Example usage of this component is provided as part of the Returns configuration guide
| Plugin Name | Returns |
|---|
Components for managing returns.
Initial changelog entry.
fc.action.field.returnitems
The following information is presented for each item that can be returned
Product details are made up of the product image, the product name and the
`orderItem.Ref`The
`ordered quantity`The
`returnable quantity``ordered quantity``returnable quantity`The return quantity selector allows the user to determine how many items should be returned for any given order line.
Allows the user to enter the specific reason the item is being returned. The value in this dropdown is configurable via the RETURN_REASONS setting. This field can be configured to be either option or mandatory when submitting a return.
Allows the user to enter the specific condition the item is being returned. The value in this dropdown is configurable via the RETURN_CONDITION setting. This field can be configured to be either option or mandatory when submitting a return.
Allows the user to write an additional comment about the item being returned. This field can be configured to be either an option or mandatory when submitting a return.
The Returns Field is configurable via the
`fc.mystique.fields.returns`Name | fc.mystique.fields.returns |
Value type | |
JSON value | |
Context | |
The
`fc.mystique.fields.returns``fc.list``fc.list``fc.mystique.fields.returns`Name | Type | Required | Default | Description |
| GraphQL query | No | Default query | The Returns field will utilize this query instead of the default if specified. |
| Component | No | No default | When specified, creates a summary component for the returns field. |
| No | See default below | Enables barcode scanning and filtering of items in the returns field. | |
| Boolean | No | False | When set to true, the returnable quantity will use the filled quantity ( When set to false, order item quantity ( |
| | No | Return reason, condition, and comment is optional | Input object will enable return reason, condition and comment to be configurable as optional or mandatory. |
Name | Type | Required | Default | Description |
| | No | | Specify the fields that upon scan, the item field searches against. Successful scans will attempt to increment the associated item quantity. |
| | No | | Specify the fields that the filter will look against when attempting to find an item. |
| | No | | The unique key that is used to identify the relevant row on successful scan. This is used to determine upon scan which row to bring into view. |
| | No | | The timeout time in milliseconds before the scanner will execute after receiving input. This is used to ensure all input values are captured before searching for a result. |
| | No | | The quantity to increment the found order item by. |
| | No | | The timeout time in milliseconds before a toast message will disappear. |
| | No | | Time in milliseconds that a row will remain highlighted after being interacted with on scan. |
| | No | | This allows to enable the phone’s camera for scanning. |
| | No | This object covers all camera relative properties. Details can be found in the table below. |
To activate the barcode scanner on the pick list, include the following setting:
`fc.mystique.fields.returns.`This is covered in the "Sample fc.mystique.fields.returns setting” section.
Name | Type | Required | Default | Description |
| | No | 10 | Frequency is the number of scan attempts per second. The frequency is an integer ranging from 1 to 10, and its default setting is 10. Opting for a higher frequency enhances scanning accuracy but also leads to greater utilization of the phone battery. To preserve the phone's battery life, it is advisable to choose a lower value. |
| | No | | The decoder in the barcode scanner specifies what kind of barcode it's searching for. It has a list (array) of possible barcode types that it checks one by one, in the order given. The decoding process stops at the first successful result. The array can include multiple barcode types, but performance decreases with each additional type. The scanner reads the entire barcode, including leading and ending zeros, without trimming it. Possible values are: |
| boolean OR | No | true | Disable the audio and haptic feedback on scan. You can configure the success and failure haptic feedback responses individually, or you can configure them together. The value is either true OR { success: boolean; fail: boolean}. This way, you can globally disable feedback by passing true or selectively disable feedback by passing { success: true }, { failure: true }, or { success: true; fail: true}. Note: Haptic feedback isn't available on iOS because of Safari constraints. On Android, a successful scan produces a single vibration, while an unsuccessful one results in two vibrations. |
| | No | 0.9 | The confidence value ranges between 0 and 1, with precision up to two decimal points. Confidence serves as a trade-off between accuracy and error margin. A higher confidence level corresponds to a reduced margin for error, especially in scenarios where the camera quality may not be excellent. |
The
`component`Name | Type | Required | Default | Description |
| | No | N/A | Enable the return condition to be optional or mandatory |
| | No | N/A | Enable the return Reason to be optional or mandatory |
| | No | N/A | Enable the return reason comment to be optional or mandatory |
Name | Type | Required | Default | Description |
| | Yes | | Toggle the validation to |
1 {
2 "enableCameraScanner": true,
3 "vAlign": "top",
4 "inputs": {
5 "returnCondition": {
6 "validation": false
7 },
8 "returnReason": {
9 "validation": false
10 },
11 "returnReasonComment": {
12 "validation": false
13 }
14 },
15 "query": "query orderById($orderId: ID!) { orderById(id: $orderId) { id ref status type createdOn updatedOn customer { ref title firstName lastName primaryPhone primaryEmail username } totalPrice totalTaxPrice items(first: 500) { edges { node { id ref quantity status totalPrice totalTaxPrice taxPrice price paidPrice currency attributes { name value } product { name ... on StandardProduct { id ref status prices { type value currency } attributes { name value } categories(first: 1) { edges { node { name } } } } ... on GroupProduct { id ref status prices { type value currency } attributes { name value } categories(first: 1) { edges { node { name } } } } ... on VariantProduct { id ref status gtin prices { type value currency } attributes { name value } categories(first: 1) { edges { node { name } } } } } } } } } }",
16 "attributes": [
17 {
18 "label": "i18n:fc.sf.ui.returns.orders.createReturnOrder.list.column.product.label",
19 "value": "{{img node.product.attributes.byName.imageUrl node.product.attributes.byName.imageUrlRef alt=node.product.name width=50 height=50 margin='0.5em'}}"
20 },
21 {
22 "label": "",
23 "type": "component",
24 "options": {
25 "component": "fc.mystique.collapsible.text",
26 "props": {
27 "text": "{{node.product.name}} - {{node.ref}}",
28 "charCutoff": 40
29 }
30 }
31 },
32 {
33 "label": "i18n:fc.sf.ui.returns.orders.createReturnOrder.list.column.description.label",
34 "type": "component",
35 "options": {
36 "component": "fc.mystique.collapsible.attributes",
37 "dataSource": "node.product.attributes",
38 "props": {
39 "exclude": [
40 "imageUrl",
41 "imageUrlRef"
42 ],
43 "collapseOn": "lines",
44 "collapseLimit": 10,
45 "hideKeys": false
46 }
47 }
48 },
49 {
50 "label": "Return Value",
51 "value": "{{currency (multiply node.totalPrice node.state.unitQuantity.quantity) node.currency}}",
52 "align": "center"
53 }
54 ],
55 "scanner": {
56 "scannerFields": [
57 "node.product.gtin"
58 ],
59 "filterFields": [
60 "node.product.gtin",
61 "node.product.name"
62 ],
63 "rowId": "node.ref",
64 "scanTimeout": 200,
65 "incrementBy": 1,
66 "toastTimeout": 2000,
67 "highlightDuration": 300
68 },
69 "summary": {
70 "descendants": [
71 {
72 "component": "fc.card.attribute",
73 "dataSource": "priceSummary",
74 "props": {
75 "title": "Returns Summary",
76 "attributes": [
77 {
78 "label": "Total Refund",
79 "value": "{{price}}"
80 }
81 ]
82 }
83 }
84 ]
85 }
86}Language: json
Name: Sample fc.mystique.fields.returns setting
Description:
[Warning: empty required content area]As aforementioned, the Returns Field component has access to the same configurability as the List Component. The Configurer can determine what columns and data to display to the user via the
`attributes``attributes`Each row of data represents one
`orderItem``orderById``orderItem`1{
2 "label": "Total Line Price",
3 "value": "{{node.totalPrice}}",
4 "align": "center"
5}Language: json
Name: orderItem
Description:
[Warning: empty required content area]Each column also has access to the state of the
`orderItem.``unitQuantity``unitQuantity``orderItem.price`The full list of
`state``orderItem`Name | Type | Description | Example Usage |
| string | The | |
| string | The users selected condition for the item. Both the | |
| string | The users selected reason for the item. Both the | |
| string | The users entered comment for the item. | |
| number | The user selected quantity for the item. | |
| boolean | Returns | |
| number | The returnable quantity for the item. | |
1{
2 "label": "Return Value",
3 "value": "{{currency (multiply node.totalPrice node.state.unitQuantity.quantity) node.currency}}",
4 "align": "center"
5}Language: json
Name: Return Value
Description:
[Warning: empty required content area]The GraphQL query used by the returns field is configurable to retrieve additional data. The default query below is used when one is not specified in the
`fc.mystique.fields.returns`1 query orderById($orderId: ID!) {
2 orderById(id: $orderId) {
3 id
4 ref
5 status
6 type
7 createdOn
8 updatedOn
9 customer {
10 ref
11 title
12 firstName
13 lastName
14 primaryPhone
15 primaryEmail
16 username
17 }
18 totalPrice
19 totalTaxPrice
20 items(first: 500) {
21 edges {
22 node {
23 id
24 ref
25 quantity
26 status
27 totalPrice
28 totalTaxPrice
29 taxPrice
30 price
31 paidPrice
32 currency
33 attributes {
34 name
35 value
36 }
37 product {
38 name
39 ... on StandardProduct {
40 id
41 ref
42 status
43 prices {
44 type
45 value
46 currency
47 }
48 attributes {
49 name
50 value
51 }
52 categories(first: 1) {
53 edges {
54 node {
55 name
56 }
57 }
58 }
59 }
60 ... on GroupProduct {
61 id
62 ref
63 status
64 prices {
65 type
66 value
67 currency
68 }
69 attributes {
70 name
71 value
72 }
73 categories(first: 1) {
74 edges {
75 node {
76 name
77 }
78 }
79 }
80 }
81 ... on VariantProduct {
82 id
83 ref
84 status
85 prices {
86 type
87 value
88 currency
89 }
90 attributes {
91 name
92 value
93 }
94 categories(first: 1) {
95 edges {
96 node {
97 name
98 }
99 }
100 }
101 }
102 }
103 }
104 }
105 }
106 }
107 }Language: graphqlschema
Name: Default GraphQL Query
Description:
[Warning: empty required content area]
The return field can produce a summary card to show the user the current expected refund amount based on the item quantities they’ve selected. This will be displayed in the “summary” slot of the action drawer or wizard page, depending on where the form is shown.
For cases where you need to show more information, or calculate the refund differently, a different display component can be provided in the configuration setting.
In order to display the summary, the setting
`fc.mystique.fields.returns``summary`Two data sources are available when determining which information to display inside the
`summary``priceSummary``orderById`The available fields when utilizing the
`priceSummary``price``taxPrice``paidPrice`Name | Description | Formula |
| The total price of all returning items. | The sum of each order item's price multiplied by the user's selected items to return. |
| The total paid price of all returning items. | The sum of each order item's paid price multiplied by the user's selected items to return. |
| The total tax price of all returning items. | The sum of each order item's tax price multiplied by the user's selected items to return. |
When setting the datasource as
`orderById``state``orderItem`1{
2 "summary": {
3 "descendants": [
4 {
5 "component": "fc.card.attribute",
6 "dataSource": "priceSummary",
7 "props": {
8 "title": "Price summary",
9 "attributes": [
10 {
11 "label": "Price",
12 "value": "{{price}}"
13 },
14 {
15 "label": "Paid price",
16 "value": "{{paidPrice}}"
17 },
18 {
19 "label": "Tax price",
20 "value": "{{taxPrice}}"
21 }
22 ]
23 }
24 }
25 ]
26 }
27}Language: json
Name: Sample Summary Configuration
Description:
[Warning: empty required content area]See Data Dictionary in the section above
n/a
N/A
Copyright © 2024 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.
