Skip to main content

Introduction

StateSet One provides a comprehensive REST and GraphQL API for Returns Management, enabling businesses to automate their entire returns process from initiation to refund. This guide will walk you through building a complete returns management system. The Returns Management module in StateSet includes various objects that facilitate the returns processes. These objects typically encompass:
  • Return
  • Return Line Items
  • Orders
  • Refunds

Returns Management Overview

Returns are an inevitable part of the eCommerce business. Customers may request returns for a variety of reasons, such as receiving a damaged or defective item, or simply changing their mind about a purchase. Regardless of the reason, it is important for businesses to have a streamlined process in place to manage returns efficiently and effectively. This helps in enhancing customer experience and building brand loyalty.

Challenges with Returns Management

Returns management can be a complex and time-consuming process. It involves multiple steps, such as generating return labels, creating returns in the system, and processing refunds. These steps are often manual and require significant time and effort. This can lead to delays in processing returns, resulting in customer dissatisfaction and loss of revenue.

StateSet’s Returns Management Solution

StateSet’s Returns Management solution automates the entire returns process, from generating return labels to processing refunds. This helps in streamlining the process and reducing the time and effort required to manage returns. The solution leverages the Temporal workflow orchestration framework to automate the various steps involved in returns management. This includes generating and emailing return labels, creating returns in StateSet, providing search capabilities for efficient record retrieval, updating customer support platforms with tracking information, and processing instant refunds. By automating the returns process, StateSet enables businesses to effectively manage and track returns, thereby enhancing customer experience and improving operational efficiency.

Prerequisites

Before you begin, ensure you have:
  • A StateSet account (Sign up here)
  • API credentials from the StateSet Cloud Console
  • Node.js 16+ installed (for SDK examples)
  • Basic understanding of REST APIs
  • Your eCommerce platform credentials (Shopify, WooCommerce, etc.)

Quickstart Guide

1

Install SDK

Install the StateSet-node SDK in your project:
2

Initialize Client

Set up your StateSet client with proper error handling:
3

Create a Return

Create a new return with validation:
4

Generate Return Label

Automatically generate and email return shipping labels:

Return Initiation

When a customer requests a return, the Returns Management workflow in StateSet is triggered. The workflow captures the necessary information from the customer, such as order details, reason for return, and any supporting documentation. Return Record

Return Label Generation and Emailing

Using the captured information, the workflow generates a return label that includes the shipping address and other relevant details. The label is then emailed to the customer, providing clear instructions on how to return the item.

Creation of a Return in StateSet

Simultaneously, the workflow creates a new return in StateSet, associating it with the corresponding order and customer information. This allows for streamlined tracking and management of the return process within the StateSet platform.

StateSet Workflow using Temporal

Temporal is an open source programming model that can simplify your code, make your applications more reliable, and help you deliver more features faster. The temporal framework allows activities to be defined and workflows to execute them based on the state or specific signals. Temporal provides the workflow management engine to combine the power of serverless API calls with a deterministic scheduler for execution. By leveraging the Temporal workflow orchestration framework, StateSet automates the entire Returns Management (RMA) process. This includes generating and emailing return labels, creating returns in StateSet, providing search capabilities for efficient record retrieval, updating customer support platforms with tracking information, and processing instant refunds. This automation streamlines the return process, enhances customer experience, and enables businesses to effectively manage and track returns. Here is an example of StateSet’s Return API using Temporal Worker & Workflow:
javascript
javascript

Search and Lookup Capabilities

The Returns Management workflow in StateSet incorporates search functionality powered by Algolia that enables easy retrieval of return information. Users can search for returns based on various criteria, such as serial number, RMA number, or order ID. This helps in quickly locating specific return records and accessing relevant details.
javascript

Instant Refunds Processing

For eligible returns, the Returns Management workflow includes instant refund processing. Once the returned item is received and inspected, the workflow automatically initiates the refund process, facilitating timely and efficient reimbursement to the customer. This eliminates delays and enhances customer satisfaction by ensuring prompt resolution of return requests.

Integration with Zendesk or Gorgias

The workflow integrates with customer support platforms like Zendesk or Gorgias to streamline communication and updates. Upon generating the return label and initiating the return process, the workflow updates the respective ticketing system with tracking information. This ensures that customer support representatives have real-time visibility into the status of returns and can provide accurate updates to customers when needed.

Aftership Tracking

javascript

Refunds

Refunds describes the general data about the goods or services being refunded to your customers. For example, you might have multiple line items on an order, each would be a separate Refund Line Item. The Refund is corresponding to the metadata regarding Refunde Items. The Refund resource has two major components:
  • Transaction records of money returned to the customer
  • The line items included in the refund, along with restocking instructions
Before you create a refund, use the calculate endpoint to generate accurate refund transactions. Specify the line items that are being refunded, their quantity and restock instructions, and whether you’re refunding shipping costs. You can then use the response of the calculate endpoint to create the actual refund. When you create a refund using the response from the calculate endpoint, you can set additional options, such as whether to notify the customer of the refund. You can refund less than the calculated amount for either shipping or the line items by setting a custom value for the amount property.

Shopify refunds

StateSet Returns Automation integrates with Shopify’s native Return APIs. For more information see the StateSet Returns Automation App on the Shopify App Store: https://apps.shopify.com/StateSet-returns-automation Here is an example of how to process a Refund using the Shopify Returns API:
javascript
If a refund includes shipping costs, or if you choose to refund line items for less than their calculated amount, then an order adjustment is created automatically to account for the discrepancy in the store’s financial reports.

WooCommerce Refunds

The return record in StateSet will include customer information such as the order id which is used to query the total order amount and tax amount. These values are used to calculate the total refund amount depending on the restocking fee. A refund can be placed via the Return record which will trigger a refund in WooCommerce and then Stripe. It may take a few days for the refund to appear on the customers debit card. The refund can be verified in StateSet by going to the Stripe returns list view. The condition and rationale from the return record can also be sent back to Zendesk from StateSet as a private message for the CSR.
javascript

Complete Returns Workflow Implementation

Here’s a production-ready implementation of a complete returns management system:

Error Handling and Recovery

Monitoring and Analytics

Best Practices

  1. Always validate return eligibility before creating a return
  2. Use idempotency keys to prevent duplicate returns
  3. Implement proper error handling with retry logic
  4. Track all return events for analytics and debugging
  5. Automate refunds for qualified returns to improve customer satisfaction
  6. Integrate with your support platform for seamless customer service
  7. Monitor return patterns to identify product issues
  8. Use webhooks for real-time status updates

Troubleshooting

  • Verify order exists and is eligible for return
  • Check API key permissions
  • Ensure all required fields are provided
  • Validate SKUs match the original order
  • Confirm shipping address is valid
  • Check carrier API credentials
  • Verify account has sufficient shipping balance
  • Try alternative carrier if primary fails
  • Ensure payment gateway credentials are configured
  • Verify refund amount doesn’t exceed original payment
  • Check for partial refunds on the order
  • Review payment processor logs

Support

For additional help with returns management: