Returns configuration

1 Introduction : managing returns with Onestock
2 Adapting the workflow
- 2.1 Simplified model
- 2.2 Advanced model
3 General configuration
- 3.1 Reasons and conditions
- 3.2 Returnability perimeter
4 Create returns from the Backoffice
5 Store App 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.

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

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.

External systems: Any other external systems can connect to our public APIs to manage returns, ensuring flexibility and integration with various platforms. API documentation is available here : API Portal - OneStock

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:

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
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
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

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
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.

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
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.
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"
        ]
    }
}