Returns configuration

Introduction : managing returns with Onestock

Onestock offers a versatile order returns management system that can be utilized through various methods to accommodate the needs of both customers and businesses. Our module ensures a seamless and efficient returns process via the following approaches:

  • Self Service Return (SSR): an iframe provided by Onestock that can be embedded directly into an e-commerce site, enabling customers to independently declare their returns.

image-20240717-080218.png
  • Store App: by activating the customer_search page in the Store App, sales people can search for customer orders and declare in-store returns.

image-20240717-080349.png
  • Backoffice: used by the customer service team, the backoffice allows for the declaration of returns using multiple pre-configured delivery methods. All returns will also be displayed in the back office, regardless of how they were created.

 

Before starting any configuration on returns, it is necessary to enable the "Return Management" module in the Backoffice. Admin users can activate it by going to the Configuration > Modules section. If the module is displayed as "not available", please refer to your Onestock contact who will make it available.

Adapting the workflow

The workflow is the foundation of the returns configuration, serving as the starting point for all return declarations, regardless of the method used. Indeed, all returns must be declared via a POST/return_parcels, and then the workflow will decide which path to take.

The workflow can be adapted with a simplified or an advanced model for returns management.

Simplified model

The simplified model manages only a single final return step, indicating that the items have been successfully returned. Generally, this step is not compatible with declarative methods such as the Self Service Return (SSR) or returns declarated in the backoffice, as these methods involve returns that are not yet finalized. However, it can be compatible with in-store returns or returns sent to Onestock via an external system.

The workflow can be configured as shown below, with a single state for the return parcel and the return line item group.

 

Return parcel workflow

Note : no action after creation is required

Return line item group workflow

Note : the action after creation update_line_item_groups_state is required to update the concerned order lines to the returned state

The process goes like this:

  1. The Store App or an external system creates a return parcel via API (POST/return_parcels). The reason, the condition, and potentially a comment can be given as parameters. The initial state of the workflow is automatically given to the return parcel: returned

  2. When the return parcel is created, Onestock automatically creates the return line item groups associated with the corresponding index ranges. The initial state of the workflow is given to the return line item groups: returned

  3. Thanks to the action after creation, the concerned line item groups are transited to the returned state

Advanced model

The advanced model allows for the order return process to be divided into two stages: declaration and validation. This model is compatible with the Self Service Return (SSR) and declarations made in the backoffice, as the return is considered 'in progress' but not yet validated. Subsequently, other systems can validate or invalidate the return, such as the Store App for in-store returns or any external system via API.

The workflow can be configured as shown below, with an initial returning state and a final state that depends on what has been declared by the validation system.

 

Return parcel workflow

Notes :

  • On the returning state, the action after creation update_return_parcels_state can be added so that the state is updated directly to returned if it comes from a validating flow (the Store App or other custom flow). For example, we can identify returns coming from the SSR via the “information” field, and set a reverse condition so that the action is not executed in these cases.

  • Then, the transition from returning to returned must update the state of the line_item group thanks to the action after update_return_line_item_groups_state

Return line item group workflow

Notes :

  • The action after creation update_line_item_groups_state is required to update the concerned order lines to the returning state

  • All outgoing transitions must be auto, as they are updated with the return parcel state change.

  • Each transition contains a condition one_return_line_item_groups_return_condition_in to check the condition of the products according to the declarations of the person who validated the return.

  • Each transition contains an action after update_line_item_groups_state in order to update the concerned order lines.

 

The return process generally involves two stages.

First: return declaration

  1. The Self Service Return, the Store App, the Backoffice, or any external system creates a return parcel via API (POST/return_parcels). The reason and potentially a comment can be given as parameters of return line item groups. The initial state of the workflow is automatically given to the return parcel: returning

  2. When the return parcel is created, Onestock automatically creates the return line item groups associated with the corresponding index ranges. The initial state of the workflow is given to the return line item groups: returning

Then: return update

The Store App or any external system can update the return parcel according to the situation.

  1. The return is accepted.

    1. A PATCH/return_parcel/{return_parcel_id}/{return_line_item_groups} updates the return_condition of line item groups, for example “like_new”.

    2. A PATCH/return_parcel/{return_parcel_id} updates the return parcel state to returned.

    3. The return_condition validates the return, and the return line item groups change their state to returned.

    4. Because of the action after, the concerned line item groups are transited to the returned state

  2. The return is received but refused (for example, if the items are damaged).

    1. A PATCH/return_parcel/{return_parcel_id}/{return_line_item_groups} updates the return_condition of line item groups, for example “used” or “refused”.

    2. A PATCH/return_parcel/{return_parcel_id} updates the return parcel state to returned.

    3. But this time, the return_condition invalidates the return, and the return line item groups change their state to return_refused.

    4. Finally, the concerned line item groups can be passed again to the fulfilled state.

  3. The return is cancelled (for example, the customer called customer service to cancel).

    1. A PATCH/return_parcel/{return_parcel_id}/{return_line_item_groups} updates the return_condition of line item groups, for example “aborted”.

    2. A PATCH/return_parcel/{return_parcel_id} updates the return parcel state to returned.

    3. The return_condition cancel the return, and the return line item groups change their state to return_aborted.

    4. Finally, the concerned line item groups can be passed again to the fulfilled state.

If the return is cancelled, it is possible to re-create a return on the same line items using the configuration "Status of return lines that can be declared in a new return". More information below.

General configuration

If the “Return Management” module is activated, the Returns tab will appear in the configuration section.

Reasons and conditions

The first two configurations allow you to offer reasons and conditions options in the interfaces (Store App, Backoffice, SSR).

Configuration

Key

Description

Example

Configuration

Key

Description

Example

Return reasons

return_management.return_reasons

Reasons for returns proposed when declaring in the Store App and Backoffice

["wrong_size","damaged_defective","incorrect_item","changed_mind","other"]

General conditions of the items

return_management.return_conditions

General conditions of items proposed for returns validation in the Store App or in other external systems.

["used","like_new","refused","aborted"]

 

Returnability perimeter

Other configurations can be used to establish the perimeter of what can and cannot be returned.

Configuration

Key

Description

Example

Configuration

Key

Description

Example

Returnable order types

return_management.policy.order_types

Types of orders that can be returned from the Store App or the Backoffice. One type is sufficient to validate the condition

["ffs","ckc"]

Returnable order line states

return_management.policy.line_item_group_states

Order line states that can be returned. Declaring a return on a different state will be refused

["fulfilled"]

 

Status of return lines that can be declared in a new return

return_management.states_to_ignore_for_duplicate_returned_line_items

By default, a return line associated with a return parcel cannot be associated with a new one. This configuration allows you to bypass this rule. For example, by configuring the return_aborted status, you can re-declare a return on the line even if the previous parcel has been cancelled

["return_aborted"]

Limit the returnable items by a query

return_management.policy.item_request

By default, all items can be returned. This configuration authorises only the items returned by the request

"stores_fr"

Returnable period

return_management.policy.time_policy.days_after_last_update.line_item_group

Period (in days) during which returns are permitted. The calculation is based on the last update of the item's state. Once this period has elapsed, an alert message is displayed in the Backoffice but the declaration is not blocked.

15

Create returns from the Backoffice

If the returns module is enabled, a "Create return" button will appear in the order options at the top right. However, the return methods must first be configured to display the options available for the return.

 

The return methods configuration must be done by sales channels. For each of them, an in_store method can be declared, as well as one or more postal methods

This configuration is in JSON format, so we advise you to copy and paste the example below to serve as a template

{ "sc_1": { "carriers": [ { "name": "colissimov2", "option": "DOM", "destination_endpoint": "001", "notifications": [ "return_with_colissimo" ], "documents": [ "return_note" ] } ], " ": { "endpoint_request": "stores_sc_1", "notifications": [ "in_store_return" ], "documents": [ "return_note" ] } }, "sc_2": { "carriers": [ { "name": "ups", "option": "ST", "destination_endpoint": "001", "notifications": [ "return_with_ups" ], "documents": [ "return_note" ] } ], "in_store": { "endpoint_request": "stores_sc_2", "notifications": [ "in_store_return" ], "documents": [ "return_note" ] } } }

Here's what each field does.

Field

Type

Validation

Description

Example

Field

Type

Validation

Description

Example

carriers

array of objects

Optional

Array of carriers proposed for the given sales channel

 

name

string

Mandatory (if carriers given)

Name of the carrier. If the carrier label is to be generated by Onestock ("ignore_shipment" not set or set to false), the carrier name must match the format expected by Onestock.

colissimov2

option

string

Mandatory (if carriers given)

Delivery option. If the carrier label is to be generated by Onestock ("ignore_shipment" not set or set to false), the option must match those expected by the carrier.

DOM

destination_endpoint

string

Mandatory (if carriers given)

Stock location to which return parcels will be sent . The stock location must be created in Onestock, and its address given.

001

ignore_shipment

bool

Optional

If the parameter is set to true, Onestock will not generate any shipping label. This makes it possible to create returns with carriers not managed by Onestock.

true

notifications

array of strings

Optional

Name of the notification that will be sent when the return parcel is created. Generally, an email. A template has been designed by our teams for adding documents as email attachments.

return_with_colissimo

documents

array of strings

Optional

Name of documents to be generated when the return parcel is created (in addition to the shipment that will be autogenerated)

return_note

in_store

object

Optional

 

 

endpoint_request

string

Mandatory (if in_store given)

Allows you to filter on a precise perimeter of stock locations proposed on the map. The stock location query must exist in Onestock.

stores_sc_1

notifications

array of strings

Optional

Name of the notification that will be sent when the return parcel is created. Generally, an email. A template has been designed by our teams for adding documents as email attachments.

in_store_return

documents

array of strings

Optional

Name of documents to be generated when the return parcel is created.

return_note

Current limitation: the address of the destination stock location is also used for the origin when the label is created, instead of the customer's address. We're working on a fix in the near future.

Store App configuration

As returns are managed from the customer_search tab in the Store App, the configuration can be found via the path Configuration > Store App > Pages settings > Customer search > Specific settings. A redirect link has been also added from the returns configuration page.

Here are more details on the configurable elements.

Configuration

Key

Description

Example

Configuration

Key

Description

Example

Returns declaration

store_app.return_options.enable

If enabled, returns can be declared on the Store App

true

Returns validation

store_app.return_options.can_validate_return

If enabled, returns in progress can be validated and declared as returned in the Store App

true

Restrict validation to the declared store

store_app.return_options.validate_only_if_destination

If enabled, only the store specified when the return was created will be able to validate it. Otherwise, all stores in the network will be able to validate it

true

Display detailed information

store_app.return_options.can_see_return_details_popin

If enable, a button appears giving access to more details about the return

true

No document generation

store_app.return_options.disable_return_note_printing

If enabled, document generation will not be proposed when the return is declared

true

Optional document generation

store_app.return_options.is_return_note_printing_optional

If enabled, document generation will not be mandatory to finalise the return declaration

true

Two configurations are currently missing from DIY (but will soon be added):

  • Return parcel states from which you can validate a return.

  • The state to which the return parcel should be transited after validation

To override these configurations, you need to make a PATCH/configurations by API by putting the following object in the keys field

"vendor_interface.page_state_params": { "return_parcel": { "to": "returned", "initial_states": [ "returning" ] } }