Skip to main content

Return lifecycle BPM

The return lifecycle in NewStore is initiated when a customer returns items from an order. The lifecycle is represented by the diagram below using the BPMN notation . These concepts are described in the Business process section.

This diagram refers to events that are emitted part of the event stream. See the entity model and the webhook.

Click here to download the BPMN image

When a customer returns items from an order, these returns can be processed in the NewStore platform via NewStore Associate App or an API. For more information, see Returning items and Managing returns to a DC .

When a return is created in the platform, NewStore checks if:

  • The item(s) returned is eligible for a refund.
  • The request for the refund is valid.

If any one of the checks fails, the return process fails and the payment refund process is not initiated. To retry the return process, contact the support team.

If both checks are successful, the return is successfully processed and the return.processed event is emitted. For blind returns for orders that originated from an external order management system , an external order ID is added to the return.processed event.

If all items in an order are returned, the shipping cost for the order is automatically refunded to the customer. The refund is processed when the last item from the order is returned. The shipping cost refund is added automatically to the total_refund_amount and related properties in the return.processed event.

For more information, see Automatic shipping cost refunds .


When shipping costs are refunded, they are indicated in the NewStore platform as returned line items with the type specified as shipping. These line items cannot be mapped to the actual product items that were returned as part of the order.

Before enabling automatic shipping cost refunds, ensure that your current integration can manage such refunds when enabled. Check your integration in a test environment after enabling the feature, before going live.

The payment refund phase starts in parallel, and the NewStore platform initiates the necessary payment refund transactions. When these transactions are completed, the payment_account.amount_refunded event is emitted. For more information on the payment refund lifecycle at NewStore, see Refunding the payment or revoking authorization .

Related topics