Returns Tutorial
How to configure the Returns Service
By default, the expiration date offset for a return request is set to 30 days.
Update the expiration date settings
You can update the expiration date offset for a tenant by sending a request to the Updating a configuration endpoint in the Configuration Service.
In the following example, we are changing the expiration date offset to 14 days.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X PUT \
'https://api.emporix.io/configuration/{tenant}/configurations/{propertyKey}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"key": "return.defaultExpiryDate",
"secured": false,
"value": "14",
"version": 1
}'
How to manage return requests
A return can be created both by a customer directly on your business' website, or by an employee on behalf of a customer.
If you want the return-service-specific events to trigger any actions of your choice, configure webhook subscriptions. See the Webhook Service Tutorials for more information.
First, ensure that the orders that you want to return (along with their order_Id values) exist in the system.
Create a return by a customer
On the storefront, a customer fills in the applicable fields in the return request:
ordersreasonmixins
Based on your tenant's configuration settings and customer's oauth token, the remaining fields are populated automatically.
When a customer sends a return request, the Creating a single return entity endpoint is called.
The following set of scopes is granted to a customer group:
returns.returns_read_own returns.returns_manage_own
The returns.returns_read and returns.returns_manage scopes are only required for employee groups.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/return/{tenant}/returns' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'saas-token: string' \
-d '{
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"quantity": 2,
"reason": {
"code": "001"
}
},
{
"id": "32102",
"quantity": 15,
"reason": {
"details": "It'\''s too small."
}
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"mixins": {
"customAttributes": {
"attr1": "value1"
}
},
"metadata": {
"mixins": {
"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/productCustomAttributesMixIn.v29.json"
}
}
}'Create a return on behalf of a customer
To create a return on behalf of a customer, you need to send a request to the Creating a single return entity endpoint.
The following set of scopes is required for an employee group:
returns.returns_read returns.returns_manage
The returns.returns_read_own and returns.returns_manage_own scopes are only required for customer groups.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X POST \
'https://api.emporix.io/return/{tenant}/returns' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'saas-token: string' \
-d '{
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"quantity": 2,
"reason": {
"code": "001"
}
},
{
"id": "32102",
"quantity": 15,
"reason": {
"details": "It'\''s too small."
}
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"mixins": {
"customAttributes": {
"attr1": "value1"
}
},
"metadata": {
"mixins": {
"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/productCustomAttributesMixIn.v29.json"
}
}
}'The approvalStatus field is automatically populated during the creation of a return and is always set to PENDING.
Update the return request by a customer
Customers can update their return request only when the approval status of the request is PENDING. When a customer updates a return, the Updating a single return endpoint is called.
The following set of scopes is granted to a customer group:
returns.returns_read_own returns.returns_manage_own
The returns.returns_read and returns.returns_manage scopes are only required for employee groups.
In this scenario, the customer updates the reason for the return.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X PUT \
'https://api.emporix.io/return/{tenant}/returns/{returnId}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'saas-token: string' \
-d '{
"id": "6369140c5c6de75d9e84c97f",
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"quantity": 2,
"reason": {
"code": "001"
}
},
{
"id": "32102",
"quantity": 15
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"mixins": {
"customAttributes": {
"attr1": "value1"
}
},
"metadata": {
"version": 1
}
}'Update the return status
As an employee, you can update all the fields available during the return creation, as well as the approvalStatus and received fields, by sending a request to the Updating a single return endpoint.
The following set of scopes is required for an employee group:
returns.returns_read returns.returns_manage
The returns.returns_read_own and returns.returns_manage_own scopes are only required for customer groups.
In this scenario, the employee updates the approval status of the return request.
To test the endpoint, open the API reference below or check the example of a curl request.
curl -i -X PUT \
'https://api.emporix.io/return/{tenant}/returns/{returnId}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'saas-token: string' \
-d '{
"id": "6369140c5c6de75d9e84c97f",
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"quantity": 2,
"reason": {
"code": "001"
}
},
{
"id": "32102",
"quantity": 15
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"mixins": {
"customAttributes": {
"attr1": "value1"
}
},
"metadata": {
"version": 1
}
}'Last updated
Was this helpful?